Reference

Blacklist

class ntokloapi.blacklist.Blacklist(key, secret, protocol='https://')[source]

Bases: ntokloapi.ntokloapi.NtokloAPIBase

_build_querystring(products)[source]

Build the querystring for the request.

This method will create the required querystring for the blacklist to work.

Parameters:products (list) – The product IDs as a python list.
Returns:A querystring ready to be tied to a URL/URI.
Return type:String

Note

This private method will strip out any querstrings that have no value. Otherwise the request and the signature would not match.

New in version 0.1.

add(productid=[])[source]

Add a product to the blacklist so it doesn’t get shown.

Parameters:productid (list) – List of product Ids to blacklist. Example: [‘123’,‘456’]
Raises:RequestError – In case the request couldn’t be made or failed.
Returns:Status code of the request. 204 No Content is the expected response.
Return type:String

New in version 0.1.

list()[source]

List the blacklisted products on an application.

This method will list all the blacklisted products on a specific application.

Raises:RequestError – In case the request couldn’t be made or failed.
Returns:JSON Object with the lsit of blacklisted elements.
Return type:JSON Object

New in version 0.1.

remove(productid=[])[source]

Remove a product from the blacklist.

This will remove a product or a list of products from the blacklist, allowing them to appear again on the recommendations to the user.

Parameters:productid (list) – List of product Ids to remove from the blacklist. Example: [‘123’,‘456’]
Raises:RequestError – In case the request couldn’t be made or failed.
Returns:Status code of the request. 204 No Content is the expected response.
Return type:String

New in version 0.1.

Charts

class ntokloapi.charts.Chart(key, secret, protocol='https://')[source]

Bases: ntokloapi.ntokloapi.NtokloAPIBase

get(date='', scope='', value='', action='', tw='', maxitems='')[source]

Request the recommendations for the application.

Parameters:
  • date (str) – (optional) The date for which to retrieve a chart. The date should be an epoch timestamp in milliseconds, truncated to midnight. Example: 1364169600000
  • scope (str) – (optional) A product attribute for which to scope recommendations. For example scope=category will consider the product category when returning recommendations. Supports: category, manufacturer, vendor.
  • value (str) – (optional) The value for the recommendation scope. For example scope=category&value=shoes will consider the shoe category when returning recommendations. The value parameter can be any string value.
  • action (str) – (optional) Filters the requested chart by conversion_funnel actions. If it’s not specified then the chart returned is all actions, equivalent to action=all.
  • tw (str) – (optional) The time window for which the charts are requested. If not specified then the chart returns daily chart, equivalent to tw=DAILY. Supports: DAILY, WEEKLY.
  • maxItems (str) – (optional) The max number of items in the charts. Default is 10. Valid range is 1-100.
Raises:

RequestError – In case the request couldn’t be made or failed.

Returns:

A JSON object with the recommendation as “items” and a “tracker_id”

Return type:

JSON Object

New in version 0.1.

Events

class ntokloapi.events.Event(key, secret, protocol='https://')[source]

Bases: ntokloapi.ntokloapi.NtokloAPIBase

send(payload, version='1.2')[source]

Create a new event on the API.

An event is some action related to a user from your platform that accesed one of your recommendations.

Parameters:
  • payload – Universal Value object (in JSON format) to be passed to the API.
  • version – (optional) Which version of the UV to use, the default is the latest one used by the ntoklo API.
Raises:

RequestError – In case the request couldn’t be made or failed.

Returns:

Status code of the request. 204 No Content is the expected response.

Return type:

String

New in version 0.1.

NtokloAPI

class ntokloapi.ntokloapi.NtokloAPIBase(key, secret, protocol='https://')[source]

Base class of the nToklo API connector

This class will take care of authentication and exceptions of the API, retuning the required codes to the functions that use it. It will also open a requests session against the API to retry in case the API connection fails.

Parameters:
  • key (str) – The user private API key. It can be obtained from the nToklo console.
  • secret (str) – The user private API secret. It can be obtained from the nToklo console.
  • protocol (str) – (optional) The protocol over to which connnect to the API. Default: https://

New in version 0.1.

get_token(uri, http_method)[source]

Get the required signature to sign the request.

Please check http://docs.ntoklo.com/start.php/authentication for more information.

Parameters:
  • uri (str) – The URI of the API resource
  • http_method (str) – HTTP method with which make the request.
Raises:
  • SignatureGenerationError – The signature didn’t match (URL of the request and the URL signed)
  • IncorrectHTTPMethod – The method is not allowed in the API.
Returns:

String containing a signed token.

Return type:

String

Products

class ntokloapi.products.Product(key, secret, protocol='https://')[source]

Bases: ntokloapi.ntokloapi.NtokloAPIBase

create(payload, version='1.2')[source]

Create a new product on the API.

A product is one of the items that you have on your catalogue.

Parameters:
  • payload (str) – Universal Value object (in JSON format) to be passed to the API.
  • version (str) – (optional) Which version of the UV to use, the default is the latest one used by the ntoklo API.
Raises:

RequestError – In case the request couldn’t be made or failed.

Returns:

Status code of the request. 204 No Content is the expected response.

Return type:

String

New in version 0.1.

Recommendations

class ntokloapi.recommendations.Recommendation(key, secret, protocol='https://')[source]

Bases: ntokloapi.ntokloapi.NtokloAPIBase

get(userid='', productid='', scope='', value='')[source]

Request the recommendations for the application.

Parameters:
  • userid (str) – (optional) the user ID number from your application.
  • productid (str) – (optional) The product ID number from your application.
  • scope (str) – (optional) A product attribute for which to scope recommendations. For example scope=category will consider the product category when returning recommendations. Supports: category, manufacturer, vendor, action.
  • value (str) – (optional) The value for the recommendation scope. For example scope=category&value=shoes will consider the shoe category when returning recommendations. The value parameter can be any string value.
Raises:

RequestError – In case the request couldn’t be made or failed.

Returns:

A JSON object with the recommendation as “items” and a “tracker_id”

Return type:

JSON Object

New in version 0.1.

Exceptions

exception ntokloapi.exceptions.IncorrectHTTPMethod(value)[source]

Bases: exceptions.Exception

A non accepted HTTP method has been used for the request.

Example

Accepted methods are GET and POST but function receives PUT.

exception ntokloapi.exceptions.IncorrectPythonVersion(value)[source]

Bases: exceptions.Exception

Throw this error whenever the signature creation has failed.

Example

The hmac module couldn’t generate the signature due to a malformed URI.

exception ntokloapi.exceptions.RequestError(value)[source]

Bases: exceptions.Exception

Throw this error whenever a request fails. Instead of letting python requests throw its own error, we capture it and show it on our own exception.

Example

Try to POST or GET a URL and have a connection error, tiemout, etc.

exception ntokloapi.exceptions.SignatureGenerationError(value)[source]

Bases: exceptions.Exception

Throw this error whenever the signature creation has failed.

Example

The hmac module couldn’t generate the signature due to a malformed URI.

Utils

class ntokloapi.utils.DictList[source]

Bases: dict

Create lists inside dictionaries with duplicate keys.

Parameters:dict (dict) – A dictionary with keys and values
Raises:KeyError – If the key if malformed
Returns:Reordered dictionary in which the same keys joined into a list.
Return type:Dictionary

References

StackOverflow: http://stackoverflow.com/a/10665285

Module contents