Universal Variable¶

The nToklo recommendation engine uses UV (Universal Variable) objects to create the recommendations. UV is a type of JSON object that has a specific set of keys to manage ecommerce entries. You can check the specification here.

Products¶

To keep track of the products, you have to send them first. It’s not a requirement but if you have a big catalog it will allow you to preprocess the data before starting to send events.

Example:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21

 import ntokloapi

 uv = {
     "version": "1.2", # If this doesn't exist, the connector will assume latest
     "product": {
         "id": "10201",
         "category": "Shoes",
         "manufacturer": "Nike",
         "currency": "GBP",
         "unit_sale_price": 98
     },
 }

 product = ntokloapi.Product(MyAPIKey, MyAPISecret)

 # If you want to send the product straight to the API
 product.create(uv)

 # In case you want to check the response
 response = product.create(uv)
 print(response)  # HTTP 204 is the expected output

Events¶

An event in the nToklo recommendation system means some kind of action that has performed by the user, and it.

Example:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31

 import ntokloapi

 # This UV is a bit special. You can send the minimum data as in the
 # example, but you can expend it with the whole information about the
 # product and the user if you want. That way if the product doesn't exist
 # it will be automatically created in the API.

 uv = {
     "version": "1.2", # If this doesn't exist, the connector will assume latest
     "user": {
         "user_id": "112"
     },
     "product": {
         "id": "10201",
     },
     "events": [
         {
             "action": "preview",
             "category": "conversion_funnel"
         }
     ]
 }

 event = ntokloapi.Event(MyAPIKey, MyAPISecret)

 # In case you want to send it straight to the API
 event.send(uv)

 # In case you want to check the response
 response = event.send(uv)
 print(response)  # HTTP 204 is the expected output

Recommendations¶

This is the core of the system, the recommendations. This function will return to you a JSON object withe the recommended products for your user and a temporary token.

Example:

1
2
3
4
5
6

 import ntokloapi

 recommendation = ntokloapi.Recommendation(MyAPIKey, MyAPISecret)
 recommendations = recommendations.get(productid='10201')

 print(recommendations)

It should return something like this:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

 {
     "tracker_id": "1d9042f0-32d3-11e5-88b8-19d6b5557055",
     "items": [
         {
             "id": "10201",
             "category": "Shoes",
             "manufacturer": "Nike"
         }
     ]
 }

Blacklist¶

The blacklist functionality allows you to add products to a blacklist so they don’t show up on the recommendations.

Example:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19

 import ntokloapi

 blacklist = ntokloapi.Blacklist(MyAPIKey, MyAPISecret)

 # Add one product to the blacklist
 blacklist.add(['10201',])

 # Add multiple rpoducts to the blacklist
 blacklist.add(['10201', '10202', '10203'])

 # Remove a product from the blacklist
 blacklist.remove(['10203',])

 # Remove multiple products from the blacklist
 blacklist.add(['10201', '10202'])

 # List all the currently blacklisted products
 blacklisted_products = blacklist.list()
 print(blacklisted_products)

Charts¶

Charts allows you to pull information regarding your analytics. It’s not a full report, for that you will have to use the nToklo Console. Charts contains a number of options that will be useful to you for filtering the information. Please refer to the Reference.

1
2
3
4
5
6

 import ntokloapi

 charts = ntokloapi.Chart(MyAPIKey, MyAPISecret)
 analytics = charts.get(date='1364169600000')

 print(analytics)

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¶