Python SDK for the Highspot API

Welcome to the official documentation for the Python SDK for the Highspot API.

Table of Contents

Change Log

This page documents the additions, changes, fixes, deprecations and removals made in each release.

Highspot Core Object

This section provides details around the core module and the methods used within the core object for the highspot package, which are listed below.


Init Module (highspot)

This module (being the primary __init__.py file for the library) provides a “jumping-off-point” to initialize the primary highspot.core.Highspot object.

Module

highspot

Synopsis

This is the __init__ module for the highspot package

Created By

Jeff Shurtliff

Last Modified

Jeff Shurtliff

Modified Date

10 Oct 2022

class highspot.Highspot(username=None, password=None, helper=None, api_version='0.5')[source]

This is the class for the core object leveraged in this library.

class Domain(hs_object)[source]

This class includes methods associated with Highspot domains.

__init__(hs_object)[source]

This method initializes the highspot.core.Highspot.Domain inner class object.

Parameters

hs_object (class[highspot.Highspot]) – The core highspot.Highspot object

get_custom_usage_labels()[source]

This method returns the custom usage labels in the user’s domain.

Returns

The custom usage labels data in JSON format

Raises

highspot.errors.exceptions.APIConnectionError

get_promoted_search_results(start=None, limit=None)[source]

This method retrieves the existing promoted search terms and their associated items.

Parameters

  • start (int, str, None) – The start position of a paged request (0 by default)

  • limit (int, str, None) – Maximum number of users returned (100 by default)

Returns

The promoted search data in JSON format

Raises

highspot.errors.exceptions.APIConnectionError

class Group(hs_object)[source]

This class includes methods associated with Highspot groups.

__init__(hs_object)[source]

This method initializes the highspot.core.Highspot.Group inner class object.

Parameters

hs_object (class[highspot.Highspot]) – The core highspot.Highspot object

get_group(group_id)[source]

This method returns the metadata for a specific group.

Parameters

group_id (str) – The unique identifier for the group

Returns

The group metadata in JSON format

Raises

highspot.errors.exceptions.APIConnectionError

get_groups(role_filter=None, right_filter=None, start=None, limit=None)[source]

This method retrieves the list of groups.

Parameters

  • role_filter (str, None) – Role by which to filter groups (editor, viewer, manager, or owner)

  • right_filter (str, None) – Right by which to filter groups (edit, view, or manage)

  • start (str, int, None) – The start position of the paged request

  • limit (str, int, None) – The maximum number of groups returned

Returns

The group list data in JSON format

Raises

highspot.errors.exceptions.APIConnectionError, highspot.errors.exceptions.InvalidFieldError

class Item(hs_object)[source]

This class includes methods associated with Highspot items.

__init__(hs_object)[source]

This method initializes the highspot.core.Highspot.Item inner class object.

Parameters

hs_object (class[highspot.Highspot]) – The core highspot.Highspot object

get_cms_metadata(item_id)[source]

This method retrieves item metadata when the item was imported through an external CMS.

Parameters

item_id (str) – The unique identifier for the specific item

Returns

The CMS metadata

Raises

highspot.errors.exceptions.APIConnectionError

get_item(item_id)[source]

This method retrieves the metadata for a specific item.

Parameters

item_id (str) – The unique identifier for the specific item

Returns

The item metadata as a dictionary

Raises

highspot.errors.exceptions.APIConnectionError

get_item_bookmarks(item_id)[source]

This method retrieves the bookmarks for a specific item.

Parameters

item_id (str) – The unique identifier for the specific item

Returns

The item bookmarks as a dictionary

Raises

highspot.errors.exceptions.APIConnectionError

get_item_content(item_id, report=False)[source]

This method retrieves the content for a specific item.

Parameters

  • item_id (str) – The unique identifier for the specific item

  • report (bool) – Indicates that the content is a report and should be returned in CSV format (False by default)

Returns

The item content or an error in plain text or as a dictionary (JSON format)

Raises

highspot.errors.exceptions.APIConnectionError

get_item_properties(item_id)[source]

This method retrieves the properties for a given item.

Parameters

item_id (str) – The unique identifier for the specific item

Returns

The properties data

Raises

highspot.errors.exceptions.APIConnectionError

get_item_property(item_id, property_name)[source]

This method retrieves a specific property for a given item.

Parameters

  • item_id (str) – The unique identifier for the specific item

  • property_name (str) – The name of the property to retrieve

Returns

The value of the property in JSON format

Raises

highspot.errors.exceptions.APIConnectionError

get_item_report(item_id)[source]

This method retrieves a CSV report for a specific item.

Parameters

item_id (str) – The unique identifier for the specific item

Returns

The item content or an error in plain text or as a dictionary (JSON format)

Raises

highspot.errors.exceptions.APIConnectionError

get_item_thumbnails(item_id)[source]

This method retrieves the thumbnail(s) for a given item.

Parameters

item_id (str) – The unique identifier for the specific item

Returns

The thumbnail data

Raises

highspot.errors.exceptions.APIConnectionError

get_items(spot_id, list_id=None, start=0, limit=100)[source]

This method retrieves the items for a specific Spot.

Parameters

  • spot_id (str) – The unique identifier for the Spot (required)

  • list_id (str, None) – The unique identifier for a list by which to filter the results

  • start (int, str) – The start position of a paged request (0 by default)

  • limit (int, str) – Maximum number of users returned (100 by default)

Returns

A dictionary containing the items

Raises

highspot.errors.exceptions.APIConnectionError

class Pitch(hs_object)[source]

This class includes methods associated with Highspot pitches.

__init__(hs_object)[source]

This method initializes the highspot.core.Highspot.Pitch inner class object.

Parameters

hs_object (class[highspot.Highspot]) – The core highspot.Highspot object

get_pitches(start=0, limit=25, sort_by='recent_activity')[source]

This method retrieves a list of the user’s pitches.

Parameters

  • start (int, str) – The start position of a paged request (0 by default)

  • limit (int, str) – Maximum number of users returned (100 by default)

  • sort_by (str) – Determines how the data is sorted (recent_activity, alphabetical, or date_created)

Returns

The pitch data in JSON format

Raises

highspot.errors.exceptions.APIConnectionError, highspot.errors.exceptions.InvalidFieldError

class Request(hs_object)[source]

This class includes methods associated with Highspot asynchronous requests.

__init__(hs_object)[source]

This method initializes the highspot.core.Highspot.Request inner class object.

Parameters

hs_object (class[highspot.Highspot]) – The core highspot.Highspot object

get_request_result(request_id)[source]

This function returns the result of an asynchronous request.

Parameters

request_id (str) – The ID of the request to check

Returns

The status of the request

Raises

highspot.errors.exceptions.APIConnectionError

get_request_status(request_id)[source]

This function returns the status of an asynchronous request.

Parameters

request_id (str) – The ID of the request to check

Returns

The status of the request

Raises

highspot.errors.exceptions.APIConnectionError

class Spot(hs_object)[source]

This class includes methods associated with Highspot spots and lists.

__init__(hs_object)[source]

This method initializes the highspot.core.Highspot.Spot inner class object.

Parameters

hs_object (class[highspot.Highspot]) – The core highspot.Highspot object

class User(hs_object)[source]

This class includes methods associated with Highspot users.

__init__(hs_object)[source]

This method initializes the highspot.core.Highspot.User inner class object.

Parameters

hs_object (class[highspot.Highspot]) – The core highspot.Highspot object

get_user(user_id)[source]

This method retrieves the metadata for a specific user.

Parameters

user_id (str) – The unique identifier for the user

Returns

The user metadata as a dictionary

Raises

highspot.errors.exceptions.APIConnectionError

get_user_properties(user_id)[source]

This method retrieves the properties for a specific user.

Parameters

user_id (str) – The unique identifier for the user

Returns

The user properties as a dictionary

Raises

highspot.errors.exceptions.APIConnectionError

get_user_property(user_id, property_name)[source]

This method retrieves a given property for a specific user.

Parameters

  • user_id (str) – The unique identifier for the user

  • property_name (str) – The name of the property value to return

Returns

The user properties as a dictionary

Raises

highspot.errors.exceptions.APIConnectionError

get_users(email=None, list_type=None, with_fields=None, exclude_fields=None, start=0, limit=100)[source]

This method retrieves a list of users.

Parameters

  • email (str, None) – An email address by which to filter the users

  • list_type (str, None) – Allows filtering by all or unverified users (filters by verified users by default)

  • with_fields (str, tuple, list, set, None) – Additional field(s) to include in the response

  • exclude_fields (str, tuple, list, set, None) – Additional field(s) to exclude in the response

  • start (int, str) – The start position of a paged request (0 by default)

  • limit (int, str) – Maximum number of users returned (100 by default)

Returns

A dictionary containing the user data

Raises

highspot.errors.exceptions.InvalidFieldError, highspot.errors.exceptions.APIConnectionError

me()[source]

This method returns the information about the user making the API call.

Returns

A dictionary with the user data

Raises

highspot.errors.exceptions.APIConnectionError

__init__(username=None, password=None, helper=None, api_version='0.5')[source]

This method instantiates the core Fresh object.

get(endpoint, return_json=True, verify_ssl=True)[source]

This method performs a GET request and will retry several times if a failure occurs.

Parameters

  • endpoint (string) – The endpoint URI to query

  • return_json (bool) – Determines if JSON data should be returned

  • verify_ssl (bool) – Determines if SSL verification should occur (True by default)

Returns

The JSON data from the response or the raw requests response.

Raises

highspot.errors.exceptions.APIConnectionError

Return to Top


Core Module (highspot.core)

This module contains the core object and functions to establish the connection to the API and leverage it to perform various actions.

Module

highspot.core

Synopsis

Defines the core highspot object used to interface with the Highspot API

Created By

Jeff Shurtliff

Last Modified

Jeff Shurtliff

Modified Date

20 Oct 2022

class highspot.core.Highspot(username=None, password=None, helper=None, api_version='0.5')[source]

This is the class for the core object leveraged in this library.

class Domain(hs_object)[source]

This class includes methods associated with Highspot domains.

__init__(hs_object)[source]

This method initializes the highspot.core.Highspot.Domain inner class object.

Parameters

hs_object (class[highspot.Highspot]) – The core highspot.Highspot object

get_custom_usage_labels()[source]

This method returns the custom usage labels in the user’s domain.

Returns

The custom usage labels data in JSON format

Raises

highspot.errors.exceptions.APIConnectionError

get_promoted_search_results(start=None, limit=None)[source]

This method retrieves the existing promoted search terms and their associated items.

Parameters

  • start (int, str, None) – The start position of a paged request (0 by default)

  • limit (int, str, None) – Maximum number of users returned (100 by default)

Returns

The promoted search data in JSON format

Raises

highspot.errors.exceptions.APIConnectionError

class Group(hs_object)[source]

This class includes methods associated with Highspot groups.

__init__(hs_object)[source]

This method initializes the highspot.core.Highspot.Group inner class object.

Parameters

hs_object (class[highspot.Highspot]) – The core highspot.Highspot object

get_group(group_id)[source]

This method returns the metadata for a specific group.

Parameters

group_id (str) – The unique identifier for the group

Returns

The group metadata in JSON format

Raises

highspot.errors.exceptions.APIConnectionError

get_groups(role_filter=None, right_filter=None, start=None, limit=None)[source]

This method retrieves the list of groups.

Parameters

  • role_filter (str, None) – Role by which to filter groups (editor, viewer, manager, or owner)

  • right_filter (str, None) – Right by which to filter groups (edit, view, or manage)

  • start (str, int, None) – The start position of the paged request

  • limit (str, int, None) – The maximum number of groups returned

Returns

The group list data in JSON format

Raises

highspot.errors.exceptions.APIConnectionError, highspot.errors.exceptions.InvalidFieldError

class Item(hs_object)[source]

This class includes methods associated with Highspot items.

__init__(hs_object)[source]

This method initializes the highspot.core.Highspot.Item inner class object.

Parameters

hs_object (class[highspot.Highspot]) – The core highspot.Highspot object

get_cms_metadata(item_id)[source]

This method retrieves item metadata when the item was imported through an external CMS.

Parameters

item_id (str) – The unique identifier for the specific item

Returns

The CMS metadata

Raises

highspot.errors.exceptions.APIConnectionError

get_item(item_id)[source]

This method retrieves the metadata for a specific item.

Parameters

item_id (str) – The unique identifier for the specific item

Returns

The item metadata as a dictionary

Raises

highspot.errors.exceptions.APIConnectionError

get_item_bookmarks(item_id)[source]

This method retrieves the bookmarks for a specific item.

Parameters

item_id (str) – The unique identifier for the specific item

Returns

The item bookmarks as a dictionary

Raises

highspot.errors.exceptions.APIConnectionError

get_item_content(item_id, report=False)[source]

This method retrieves the content for a specific item.

Parameters

  • item_id (str) – The unique identifier for the specific item

  • report (bool) – Indicates that the content is a report and should be returned in CSV format (False by default)

Returns

The item content or an error in plain text or as a dictionary (JSON format)

Raises

highspot.errors.exceptions.APIConnectionError

get_item_properties(item_id)[source]

This method retrieves the properties for a given item.

Parameters

item_id (str) – The unique identifier for the specific item

Returns

The properties data

Raises

highspot.errors.exceptions.APIConnectionError

get_item_property(item_id, property_name)[source]

This method retrieves a specific property for a given item.

Parameters

  • item_id (str) – The unique identifier for the specific item

  • property_name (str) – The name of the property to retrieve

Returns

The value of the property in JSON format

Raises

highspot.errors.exceptions.APIConnectionError

get_item_report(item_id)[source]

This method retrieves a CSV report for a specific item.

Parameters

item_id (str) – The unique identifier for the specific item

Returns

The item content or an error in plain text or as a dictionary (JSON format)

Raises

highspot.errors.exceptions.APIConnectionError

get_item_thumbnails(item_id)[source]

This method retrieves the thumbnail(s) for a given item.

Parameters

item_id (str) – The unique identifier for the specific item

Returns

The thumbnail data

Raises

highspot.errors.exceptions.APIConnectionError

get_items(spot_id, list_id=None, start=0, limit=100)[source]

This method retrieves the items for a specific Spot.

Parameters

  • spot_id (str) – The unique identifier for the Spot (required)

  • list_id (str, None) – The unique identifier for a list by which to filter the results

  • start (int, str) – The start position of a paged request (0 by default)

  • limit (int, str) – Maximum number of users returned (100 by default)

Returns

A dictionary containing the items

Raises

highspot.errors.exceptions.APIConnectionError

class Pitch(hs_object)[source]

This class includes methods associated with Highspot pitches.

__init__(hs_object)[source]

This method initializes the highspot.core.Highspot.Pitch inner class object.

Parameters

hs_object (class[highspot.Highspot]) – The core highspot.Highspot object

get_pitches(start=0, limit=25, sort_by='recent_activity')[source]

This method retrieves a list of the user’s pitches.

Parameters

  • start (int, str) – The start position of a paged request (0 by default)

  • limit (int, str) – Maximum number of users returned (100 by default)

  • sort_by (str) – Determines how the data is sorted (recent_activity, alphabetical, or date_created)

Returns

The pitch data in JSON format

Raises

highspot.errors.exceptions.APIConnectionError, highspot.errors.exceptions.InvalidFieldError

class Request(hs_object)[source]

This class includes methods associated with Highspot asynchronous requests.

__init__(hs_object)[source]

This method initializes the highspot.core.Highspot.Request inner class object.

Parameters

hs_object (class[highspot.Highspot]) – The core highspot.Highspot object

get_request_result(request_id)[source]

This function returns the result of an asynchronous request.

Parameters

request_id (str) – The ID of the request to check

Returns

The status of the request

Raises

highspot.errors.exceptions.APIConnectionError

get_request_status(request_id)[source]

This function returns the status of an asynchronous request.

Parameters

request_id (str) – The ID of the request to check

Returns

The status of the request

Raises

highspot.errors.exceptions.APIConnectionError

class Spot(hs_object)[source]

This class includes methods associated with Highspot spots and lists.

__init__(hs_object)[source]

This method initializes the highspot.core.Highspot.Spot inner class object.

Parameters

hs_object (class[highspot.Highspot]) – The core highspot.Highspot object

class User(hs_object)[source]

This class includes methods associated with Highspot users.

__init__(hs_object)[source]

This method initializes the highspot.core.Highspot.User inner class object.

Parameters

hs_object (class[highspot.Highspot]) – The core highspot.Highspot object

get_user(user_id)[source]

This method retrieves the metadata for a specific user.

Parameters

user_id (str) – The unique identifier for the user

Returns

The user metadata as a dictionary

Raises

highspot.errors.exceptions.APIConnectionError

get_user_properties(user_id)[source]

This method retrieves the properties for a specific user.

Parameters

user_id (str) – The unique identifier for the user

Returns

The user properties as a dictionary

Raises

highspot.errors.exceptions.APIConnectionError

get_user_property(user_id, property_name)[source]

This method retrieves a given property for a specific user.

Parameters

  • user_id (str) – The unique identifier for the user

  • property_name (str) – The name of the property value to return

Returns

The user properties as a dictionary

Raises

highspot.errors.exceptions.APIConnectionError

get_users(email=None, list_type=None, with_fields=None, exclude_fields=None, start=0, limit=100)[source]

This method retrieves a list of users.

Parameters

  • email (str, None) – An email address by which to filter the users

  • list_type (str, None) – Allows filtering by all or unverified users (filters by verified users by default)

  • with_fields (str, tuple, list, set, None) – Additional field(s) to include in the response

  • exclude_fields (str, tuple, list, set, None) – Additional field(s) to exclude in the response

  • start (int, str) – The start position of a paged request (0 by default)

  • limit (int, str) – Maximum number of users returned (100 by default)

Returns

A dictionary containing the user data

Raises

highspot.errors.exceptions.InvalidFieldError, highspot.errors.exceptions.APIConnectionError

me()[source]

This method returns the information about the user making the API call.

Returns

A dictionary with the user data

Raises

highspot.errors.exceptions.APIConnectionError

__init__(username=None, password=None, helper=None, api_version='0.5')[source]

This method instantiates the core Fresh object.

get(endpoint, return_json=True, verify_ssl=True)[source]

This method performs a GET request and will retry several times if a failure occurs.

Parameters

  • endpoint (string) – The endpoint URI to query

  • return_json (bool) – Determines if JSON data should be returned

  • verify_ssl (bool) – Determines if SSL verification should occur (True by default)

Returns

The JSON data from the response or the raw requests response.

Raises

highspot.errors.exceptions.APIConnectionError

Return to Top


Core Functionality Subclasses (highspot.core.Highspot)

These classes below are inner/nested classes within the core highspot.core.Highspot class.

Note

The classes themselves are PascalCase format and singular (e.g. Item, User, etc.) whereas the names used to call the inner class methods are all lowercase (or snake_case) and plural. (e.g. core_object.items.get_item(), core_object.users.get_user(), etc.)

Domain Subclass (highspot.core.Highspot.Domain)
class Highspot.Domain(hs_object)[source]

This class includes methods associated with Highspot domains.

get_custom_usage_labels()[source]

This method returns the custom usage labels in the user’s domain.

Returns

The custom usage labels data in JSON format

Raises

highspot.errors.exceptions.APIConnectionError

get_promoted_search_results(start=None, limit=None)[source]

This method retrieves the existing promoted search terms and their associated items.

Parameters

  • start (int, str, None) – The start position of a paged request (0 by default)

  • limit (int, str, None) – Maximum number of users returned (100 by default)

Returns

The promoted search data in JSON format

Raises

highspot.errors.exceptions.APIConnectionError

Return to Top

Groups Subclass (highspot.core.Highspot.Group)
class Highspot.Group(hs_object)[source]

This class includes methods associated with Highspot groups.

get_group(group_id)[source]

This method returns the metadata for a specific group.

Parameters

group_id (str) – The unique identifier for the group

Returns

The group metadata in JSON format

Raises

highspot.errors.exceptions.APIConnectionError

get_groups(role_filter=None, right_filter=None, start=None, limit=None)[source]

This method retrieves the list of groups.

Parameters

  • role_filter (str, None) – Role by which to filter groups (editor, viewer, manager, or owner)

  • right_filter (str, None) – Right by which to filter groups (edit, view, or manage)

  • start (str, int, None) – The start position of the paged request

  • limit (str, int, None) – The maximum number of groups returned

Returns

The group list data in JSON format

Raises

highspot.errors.exceptions.APIConnectionError, highspot.errors.exceptions.InvalidFieldError

Return to Top

Items Subclass (highspot.core.Highspot.Item)
class Highspot.Item(hs_object)[source]

This class includes methods associated with Highspot items.

get_cms_metadata(item_id)[source]

This method retrieves item metadata when the item was imported through an external CMS.

Parameters

item_id (str) – The unique identifier for the specific item

Returns

The CMS metadata

Raises

highspot.errors.exceptions.APIConnectionError

get_item(item_id)[source]

This method retrieves the metadata for a specific item.

Parameters

item_id (str) – The unique identifier for the specific item

Returns

The item metadata as a dictionary

Raises

highspot.errors.exceptions.APIConnectionError

get_item_bookmarks(item_id)[source]

This method retrieves the bookmarks for a specific item.

Parameters

item_id (str) – The unique identifier for the specific item

Returns

The item bookmarks as a dictionary

Raises

highspot.errors.exceptions.APIConnectionError

get_item_content(item_id, report=False)[source]

This method retrieves the content for a specific item.

Parameters

  • item_id (str) – The unique identifier for the specific item

  • report (bool) – Indicates that the content is a report and should be returned in CSV format (False by default)

Returns

The item content or an error in plain text or as a dictionary (JSON format)

Raises

highspot.errors.exceptions.APIConnectionError

get_item_properties(item_id)[source]

This method retrieves the properties for a given item.

Parameters

item_id (str) – The unique identifier for the specific item

Returns

The properties data

Raises

highspot.errors.exceptions.APIConnectionError

get_item_property(item_id, property_name)[source]

This method retrieves a specific property for a given item.

Parameters

  • item_id (str) – The unique identifier for the specific item

  • property_name (str) – The name of the property to retrieve

Returns

The value of the property in JSON format

Raises

highspot.errors.exceptions.APIConnectionError

get_item_report(item_id)[source]

This method retrieves a CSV report for a specific item.

Parameters

item_id (str) – The unique identifier for the specific item

Returns

The item content or an error in plain text or as a dictionary (JSON format)

Raises

highspot.errors.exceptions.APIConnectionError

get_item_thumbnails(item_id)[source]

This method retrieves the thumbnail(s) for a given item.

Parameters

item_id (str) – The unique identifier for the specific item

Returns

The thumbnail data

Raises

highspot.errors.exceptions.APIConnectionError

get_items(spot_id, list_id=None, start=0, limit=100)[source]

This method retrieves the items for a specific Spot.

Parameters

  • spot_id (str) – The unique identifier for the Spot (required)

  • list_id (str, None) – The unique identifier for a list by which to filter the results

  • start (int, str) – The start position of a paged request (0 by default)

  • limit (int, str) – Maximum number of users returned (100 by default)

Returns

A dictionary containing the items

Raises

highspot.errors.exceptions.APIConnectionError

Return to Top

Pitches Subclass (highspot.core.Highspot.Pitch)
class Highspot.Pitch(hs_object)[source]

This class includes methods associated with Highspot pitches.

get_pitches(start=0, limit=25, sort_by='recent_activity')[source]

This method retrieves a list of the user’s pitches.

Parameters

  • start (int, str) – The start position of a paged request (0 by default)

  • limit (int, str) – Maximum number of users returned (100 by default)

  • sort_by (str) – Determines how the data is sorted (recent_activity, alphabetical, or date_created)

Returns

The pitch data in JSON format

Raises

highspot.errors.exceptions.APIConnectionError, highspot.errors.exceptions.InvalidFieldError

Return to Top

Request Subclass (highspot.core.Highspot.Request)
class Highspot.Request(hs_object)[source]

This class includes methods associated with Highspot asynchronous requests.

get_request_result(request_id)[source]

This function returns the result of an asynchronous request.

Parameters

request_id (str) – The ID of the request to check

Returns

The status of the request

Raises

highspot.errors.exceptions.APIConnectionError

get_request_status(request_id)[source]

This function returns the status of an asynchronous request.

Parameters

request_id (str) – The ID of the request to check

Returns

The status of the request

Raises

highspot.errors.exceptions.APIConnectionError

Return to Top

Spots Subclass (highspot.core.Highspot.Spot)
class Highspot.Spot(hs_object)[source]

This class includes methods associated with Highspot spots and lists.

Return to Top

Users Subclass (highspot.core.Highspot.User)
class Highspot.User(hs_object)[source]

This class includes methods associated with Highspot users.

get_user(user_id)[source]

This method retrieves the metadata for a specific user.

Parameters

user_id (str) – The unique identifier for the user

Returns

The user metadata as a dictionary

Raises

highspot.errors.exceptions.APIConnectionError

get_user_properties(user_id)[source]

This method retrieves the properties for a specific user.

Parameters

user_id (str) – The unique identifier for the user

Returns

The user properties as a dictionary

Raises

highspot.errors.exceptions.APIConnectionError

get_user_property(user_id, property_name)[source]

This method retrieves a given property for a specific user.

Parameters

  • user_id (str) – The unique identifier for the user

  • property_name (str) – The name of the property value to return

Returns

The user properties as a dictionary

Raises

highspot.errors.exceptions.APIConnectionError

get_users(email=None, list_type=None, with_fields=None, exclude_fields=None, start=0, limit=100)[source]

This method retrieves a list of users.

Parameters

  • email (str, None) – An email address by which to filter the users

  • list_type (str, None) – Allows filtering by all or unverified users (filters by verified users by default)

  • with_fields (str, tuple, list, set, None) – Additional field(s) to include in the response

  • exclude_fields (str, tuple, list, set, None) – Additional field(s) to exclude in the response

  • start (int, str) – The start position of a paged request (0 by default)

  • limit (int, str) – Maximum number of users returned (100 by default)

Returns

A dictionary containing the user data

Raises

highspot.errors.exceptions.InvalidFieldError, highspot.errors.exceptions.APIConnectionError

me()[source]

This method returns the information about the user making the API call.

Returns

A dictionary with the user data

Raises

highspot.errors.exceptions.APIConnectionError

Return to Top


Primary Modules

This section provides details around the primary modules used in the highspot package, which are listed below.


Init Module (highspot)

The Init Module is covered on this page.


Core Module (highspot.core)

The Core Module is covered on this page.


API Module (highspot.api)

This module handles interactions with the Highspot API.

Module

highspot.api

Synopsis

This module handles interactions with the Highspot REST API

Created By

Jeff Shurtliff

Last Modified

Jeff Shurtliff

Modified Date

16 Oct 2022

highspot.api.get_request_with_retries(hs_object, endpoint, return_json=True, verify_ssl=True)[source]

This function performs a GET request and will retry several times if a failure occurs.

Parameters

  • hs_object – The Highspot object

  • endpoint (string) – The endpoint URI to query

  • return_json (bool) – Determines if JSON data should be returned

  • verify_ssl (bool) – Determines if SSL verification should occur (True by default)

Returns

The JSON data from the response or the raw requests response.

Raises

highspot.errors.exceptions.APIConnectionError

Return to Top


Domain Module (highspot.domain)

This module handles interactions with Highspot domains.

Module

highspot.domain

Synopsis

Defines the domain-related functions associated with the Highspot API

Created By

Jeff Shurtliff

Last Modified

Jeff Shurtliff

Modified Date

17 Oct 2022

highspot.domain.get_custom_usage_labels(hs_object)[source]

This function returns the custom usage labels in the user’s domain.

Parameters

hs_object (class[highspot.Highspot]) – The core highspot.Highspot object

Returns

The custom usage labels data in JSON format

Raises

highspot.errors.exceptions.APIConnectionError

highspot.domain.get_promoted_search_results(hs_object, start=None, limit=None)[source]

This function retrieves the existing promoted search terms and their associated items.

Parameters

  • hs_object (class[highspot.Highspot]) – The core highspot.Highspot object

  • start (int, str, None) – The start position of a paged request (0 by default)

  • limit (int, str, None) – Maximum number of users returned (100 by default)

Returns

The promoted search data in JSON format

Raises

highspot.errors.exceptions.APIConnectionError

Return to Top


Groups Module (highspot.groups)

This module handles interactions with Highspot groups.

Module

highspot.groups

Synopsis

Defines the group-related functions associated with the Highspot API

Created By

Jeff Shurtliff

Last Modified

Jeff Shurtliff

Modified Date

16 Oct 2022

highspot.groups.get_group(hs_object, group_id)[source]

This function returns the metadata for a specific group.

Parameters
Returns

The group metadata in JSON format

Raises

highspot.errors.exceptions.APIConnectionError

highspot.groups.get_groups(hs_object, role_filter=None, right_filter=None, start=None, limit=None)[source]

This function retrieves the list of groups.

Parameters

  • hs_object (class[highspot.Highspot]) – The core highspot.Highspot object

  • role_filter (str, None) – Role by which to filter groups (editor, viewer, manager, or owner)

  • right_filter (str, None) – Right by which to filter groups (edit, view, or manage)

  • start (str, int, None) – The start position of the paged request

  • limit (str, int, None) – The maximum number of groups returned

Returns

The group list data in JSON format

Raises

highspot.errors.exceptions.APIConnectionError, highspot.errors.exceptions.InvalidFieldError

Return to Top


Items Module (highspot.items)

This module handles interactions with Highspot items.

Module

highspot.items

Synopsis

Defines the item-related functions associated with the Highspot API

Created By

Jeff Shurtliff

Last Modified

Jeff Shurtliff

Modified Date

16 Oct 2022

highspot.items.get_cms_metadata(hs_object, item_id)[source]

This function retrieves item metadata when the item was imported through an external CMS.

Parameters
Returns

The CMS metadata

Raises

highspot.errors.exceptions.APIConnectionError

highspot.items.get_item(hs_object, item_id)[source]

This function retrieves the metadata for a specific item.

Parameters
Returns

The item metadata as a dictionary

Raises

highspot.errors.exceptions.APIConnectionError

highspot.items.get_item_bookmarks(hs_object, item_id)[source]

This function retrieves the bookmarks for a specific item.

Parameters
Returns

The item bookmarks as a dictionary

Raises

highspot.errors.exceptions.APIConnectionError

highspot.items.get_item_content(hs_object, item_id, report=False)[source]

This function retrieves the content for a specific item.

Parameters

  • hs_object (class[highspot.Highspot]) – The core highspot.Highspot object

  • item_id (str) – The unique identifier for the specific item

  • report (bool) – Indicates that the content is a report and should be returned in CSV format (False by default)

Returns

The item content or an error in plain text or as a dictionary (JSON format)

Raises

highspot.errors.exceptions.APIConnectionError

highspot.items.get_item_properties(hs_object, item_id)[source]

This function retrieves the properties for a given item.

Parameters
Returns

The properties data in JSON format

Raises

highspot.errors.exceptions.APIConnectionError

highspot.items.get_item_property(hs_object, item_id, property_name)[source]

This function retrieves a specific property for a given item.

Parameters
Returns

The value of the property in JSON format

Raises

highspot.errors.exceptions.APIConnectionError

highspot.items.get_item_report(hs_object, item_id)[source]

This function retrieves a CSV report for a specific item.

Parameters
Returns

The item content or an error in plain text or as a dictionary (JSON format)

Raises

highspot.errors.exceptions.APIConnectionError

highspot.items.get_item_thumbnails(hs_object, item_id)[source]

This function retrieves the thumbnail(s) for a given item.

Parameters
Returns

The thumbnail data

Raises

highspot.errors.exceptions.APIConnectionError

highspot.items.get_items(hs_object, spot_id, list_id=None, start=0, limit=100)[source]

This function retrieves the items for a specific Spot.

Parameters

  • hs_object (class[highspot.Highspot]) – The core highspot.Highspot object

  • spot_id (str) – The unique identifier for the Spot (required)

  • list_id (str, None) – The unique identifier for a list by which to filter the results

  • start (int, str) – The start position of a paged request (0 by default)

  • limit (int, str) – Maximum number of users returned (100 by default)

Returns

A dictionary containing the items

Raises

highspot.errors.exceptions.APIConnectionError

Return to Top


Pitches Module (highspot.pitches)

This module handles interactions with Highspot pitches.

Module

highspot.pitches

Synopsis

Defines the pitch-related functions associated with the Highspot API

Created By

Jeff Shurtliff

Last Modified

Jeff Shurtliff

Modified Date

17 Oct 2022

highspot.pitches.get_pitches(hs_object, start=0, limit=25, sort_by='recent_activity')[source]

This function retrieves a list of the user’s pitches.

Parameters

  • hs_object (class[highspot.Highspot]) – The core highspot.Highspot object

  • start (int, str) – The start position of a paged request (0 by default)

  • limit (int, str) – Maximum number of users returned (100 by default)

  • sort_by (str) – Determines how the data is sorted (recent_activity, alphabetical, or date_created)

Returns

The pitch data in JSON format

Raises

highspot.errors.exceptions.APIConnectionError, highspot.errors.exceptions.InvalidFieldError

Return to Top


Request Module (highspot.request)

This module handles interactions with Highspot asynchronous requests.

Module

highspot.domain

Synopsis

Defines the domain-related functions associated with the Highspot API

Created By

Jeff Shurtliff

Last Modified

Jeff Shurtliff

Modified Date

20 Oct 2022

highspot.request.get_request_result(hs_object, request_id)[source]

This function returns the result of an asynchronous request.

Parameters
Returns

The status of the request

Raises

highspot.errors.exceptions.APIConnectionError

highspot.request.get_request_status(hs_object, request_id)[source]

This function returns the status of an asynchronous request.

Parameters
Returns

The status of the request

Raises

highspot.errors.exceptions.APIConnectionError

Return to Top


Spots Module (highspot.spots)

This module handles interactions with Highspot spots and lists.

Module

highspot.spots

Synopsis

Defines the spot-related functions associated with the Highspot API

Created By

Jeff Shurtliff

Last Modified

Jeff Shurtliff

Modified Date

16 Oct 2022

Return to Top


Users Module (highspot.users)

This module handles interactions with Highspot users.

Module

highspot.users

Synopsis

Defines the users-related functions associated with the Highspot API

Created By

Jeff Shurtliff

Last Modified

Jeff Shurtliff

Modified Date

16 Oct 2022

highspot.users.get_user(hs_object, user_id)[source]

This function retrieves the metadata for a specific user.

Parameters
Returns

The user metadata as a dictionary

Raises

highspot.errors.exceptions.APIConnectionError

highspot.users.get_user_properties(hs_object, user_id)[source]

This function retrieves the properties for a specific user.

Parameters
Returns

The user properties as a dictionary

Raises

highspot.errors.exceptions.APIConnectionError

highspot.users.get_user_property(hs_object, user_id, property_name)[source]

This function retrieves a given property for a specific user.

Parameters
Returns

The user properties as a dictionary

Raises

highspot.errors.exceptions.APIConnectionError

highspot.users.get_users(hs_object, email=None, list_type=None, with_fields=None, exclude_fields=None, start=0, limit=100)[source]

This function retrieves a list of users.

Parameters

  • hs_object (class[highspot.Highspot]) – The core highspot.Highspot object

  • email (str, None) – An email address by which to filter the users

  • list_type (str, None) – Allows filtering by all or unverified users (filters by verified users by default)

  • with_fields (str, tuple, list, set, None) – Additional field(s) to include in the response

  • exclude_fields (str, tuple, list, set, None) – Additional field(s) to exclude in the response

  • start (int, str) – The start position of a paged request (0 by default)

  • limit (int, str) – Maximum number of users returned (100 by default)

Returns

A dictionary containing the user data

Raises

highspot.errors.exceptions.InvalidFieldError, highspot.errors.exceptions.APIConnectionError

highspot.users.me(hs_object)[source]

This function returns the information about the user making the API call.

Parameters

hs_object (class[highspot.Highspot]) – The core highspot.Highspot object

Returns

A dictionary with the user data

Raises

highspot.errors.exceptions.APIConnectionError

Return to Top


Supporting Modules

This section provides details around the supporting modules used in the highspot package, which are listed below.


Classes & Exceptions

This section includes modules that contain the classes and exceptions used throughout the package.


Errors Module (highspot.errors)

This module contains all of the exception classes and error handling functions leveraged throughout the library.

Package

highspot.errors

Synopsis

This module includes custom exceptions and handlers

Created By

Jeff Shurtliff

Last Modified

Jeff Shurtliff

Modified Date

11 Oct 2022

Return to Top


Exceptions Module (highspot.errors.exceptions)

This sub-module contains all of the exception classes leveraged in functions throughout the library.

Module

highspot.errors.exceptions

Synopsis

Collection of exception classes relating to the highspot library

Created By

Jeff Shurtliff

Last Modified

Jeff Shurtliff

Modified Date

16 Oct 2022

exception highspot.errors.exceptions.APIConnectionError(*args, **kwargs)[source]

This exception is used when the API query could not be completed due to connection aborts and/or timeouts.

exception highspot.errors.exceptions.APIRequestError(*args, **kwargs)[source]

This exception is used for generic API request errors when there isn’t a more specific exception.

exception highspot.errors.exceptions.CurrentlyUnsupportedError(*args, **kwargs)[source]

This exception is used when a feature or functionality being used is currently unsupported.

exception highspot.errors.exceptions.DataMismatchError(*args, **kwargs)[source]

This exception is used when there is a mismatch between two data sources.

exception highspot.errors.exceptions.HighspotError[source]

This is the base class for Highspot exceptions.

exception highspot.errors.exceptions.InvalidFieldError(*args, **kwargs)[source]

This exception is used when an invalid field is provided.

exception highspot.errors.exceptions.MissingAuthDataError(*args, **kwargs)[source]

This exception is used when authentication data is not supplied and therefore a connection cannot occur.

exception highspot.errors.exceptions.MissingRequiredDataError(*args, **kwargs)[source]

This exception is used when a function or method is missing one or more required arguments.

Return to Top


Handlers Module (highspot.errors.handlers)

This sub-module contains various error handling functions that are leveraged throughout the library.

Module

highspot.errors.handlers

Synopsis

Functions that handle various error situations within the namespace

Created By

Jeff Shurtliff

Last Modified

Jeff Shurtliff

Modified Date

11 Oct 2022

highspot.errors.handlers.eprint(*args, **kwargs)[source]

This function behaves the same as the print() function but is leveraged to print errors to sys.stderr.

Return to Top


Tools & Utilities

This section includes modules that contain tools and utilities leveraged by other scripts.


Logging Utilities Module (highspot.utils.log_utils)

This module includes various utilities to assist with logging.

Module

highspot.utils.log_utils

Synopsis

Collection of logging utilities and functions

Usage

from highspot.utils import log_utils

Example

logger = log_utils.initialize_logging(__name__)

Created By

Jeff Shurtliff

Last Modified

Jeff Shurtliff

Modified Date

16 Oct 2022

class highspot.utils.log_utils.LessThanFilter(exclusive_maximum, name='')[source]

This class allows filters to be set to limit log levels to only less than a specified level.

See also

Zoey Greer is the original author of this class which was provided on Stack Overflow.

filter(record)[source]

This method returns a Boolean integer value indicating whether or not a message should be logged.

Note

A non-zero return indicates that the message will be logged.

highspot.utils.log_utils.initialize_logging(logger_name=None, log_level=None, formatter=None, debug=None, no_output=None, file_output=None, file_log_level=None, log_file=None, overwrite_log_files=None, console_output=None, console_log_level=None, syslog_output=None, syslog_log_level=None, syslog_address=None, syslog_port=None)[source]

This function initializes logging for the highspot library.

Return to Top


Version Module (highspot.utils.version)

This module is the primary source of the current version of the highspot package.

Module

highspot.utils.version

Synopsis

This simple script contains the package version

Created By

Jeff Shurtliff

Last Modified

Jeff Shurtliff

Modified Date

11 Dec 2022

highspot.utils.version.get_full_version()[source]

This function returns the current full version of the highspot package.

highspot.utils.version.get_major_minor_version()[source]

This function returns the current major.minor (i.e. X.Y) version of the highspot package.

Return to Top