API - Backend interactions

What you'll need

Before using TasteHit's API, you will need to:

  1. Get an account (sign up here)
  2. Configure access to your product catalog (sign up here)
  3. Create a new widget and set it up as an API endpoint here

Basics

TasteHit generates product selections based on anonymous interaction data. Interactions are events that take place between your shop's visitors and your products: page view, add-to-cart, click on a recommendation. These interactions are sent to TasteHit where they are processed. When a recommendation is to be generated, TasteHit exploits this data and returns a list of recommendations. The two relevant actions are therefore:

  1. An interaction took place between a visitor and a product. This information has to be sent to TasteHit.
  2. A list of recommendations is requested

The TasteHit API exposes a URL for each of these two interactions.

  1. Signal an interaction:

    1
    POST https://www.tastehit.com/api/{customer}/v1/interaction/{user}/{item}/{action}
    

    This interaction request sends information to TasteHit (POST) and can be interpreted as: the user identified by {user} interacted with product {item} by performing action {action} on the customer's site {customer}.

  2. Request recommendations:

    1
    GET https://www.tastehit.com/api/{customer}/v1/{algorithm}/r
    

    A request for recommendations (GET) can be interpreted as requesting a list of recommendations for user {user} on the customer site {customer}.

Description of parameters

In the previous two requests, some special parameters were used. The following table gives a detailed description of each one of them.

Name Description Type
customer

Your TasteHit Customer ID, which can be found in your profile if you are logged in.

string
user

An ID you gave to a user who interacts with your application. This user is usually defined and managed in your backend. It has to be a unique identifier, but can be any type of data which is convenient for you to use and keep track of: random string, cookie id, email.

E.g. john.doe@mail.com, gojoq9mnjdlpmefcxjb42vl99tuapw2j, my_user_11493

Note: TasteHit keeps track of user ids, so there is no need to "create" or "register" a user before sending interaction data for that user.

For interaction requests (POST), {user} is the user who interacted with a product in some way.

For recommendation requests (GET), {user} is the user for whom a list of recommendations is requested.

string
item

The unique product identifier of a product. This identifier has to be unique and correspond to the Unique ID, as configured in your catalog .

If the unique ID contains spaces or any other characters which are not allowed in URLs, please make sure that you URL-encode this unique identifier (for example encodeURIComponent("Visitor 1") in JavaScript).

  • In interaction requests (POST), this is the item with which the user interacted.
    E.g.:
    • /api/customerX/v1/interaction/bob/item1/visit - means "user bob visited the item with the unique ID 'item1'".
    • /api/customerX/v1/interaction/bob/item2/follow - means "user bob clicked on a recommendation for the product with the Unique ID 'item2'".
  • For recommendation requests (GET), {item} represent the item of context. This means that the recommendations have to take into account that the user {user} is currently on the product page of item {item} (the item of context), in addition to this user's browsing history.
string
action
The type of interaction between a user and a product.
Here are the values which are already configured by TasteHit:
  • visit: A visitor loaded a product page.
  • follow: A visitor clicked on a recommendation made by TasteHit.
  • cart: A visitor added a product to his cart.
Custom actions can be configured here. Actions can be added, modified, or deleted at any time (you have to wait a few hours before the changes are picked up by your API).

API calls that you make for these custom actions need to be done "at the right moment" for the names of the actions to correspond to their actual function. For example calling the POST route with a custom action called quickview has to be called when a user clicks on the "quickview" button of a product displayed on a category page.
string
algorithm
The ID used as a new API endpoint (also called widgetID). These algorithm/widgetIDs can be configured in the "Configuration / Widgets" section of the dashboard. Configuration parameters include the default algorithm and filters to be used when the API endpoint is called.
string
resort

(optional) Used in recommendation GET requests in order to resort items in an itemarray.
Possible values are:

  • popular
  • unpopular
  • foruser
  • random

string
itemarray

(optional) Used in recommendation GET requests in combination with resort.

URL-encoded array
pscore

(optional) The maximum score value. Used for pagination in recommendation GET requests. No recommendations with a score equal or higher to this value will be returned.

float
limit

(optional) The number of recommendations requested. E.g. setting limit=2 means that at most two recommendations will be returned.
Default: 5.

integer
filters

Restrict the desired recommendations with filters.
Example filters:

  • [{brand: "Desigual"}]
  • [{brand: "Desigual", exclusive: true}]
  • [{brand: "Desigual", similar_to: true}]
  • [{brand: "Desigual", exclusive: true, similar_to: true}]
  • [{brand: "Desigual"}, {color: "black"}, {price: {min: 50.0, max: 100.0}}, {something_else: {min: -12.433}}, {available: true}]

string
(URL-encoded JSON)

Sending data to TasteHit

For TasteHit's recommendations to make sense, you should notify TasteHit each time a visitor interacts with a product. In order to do that, the following route has to be used:

1
POST https://www.tastehit.com/api/{customer}/v1/interaction/{user}/{item}/{action}

For example, when user "bob" visits the product page of a product with Unique ID "item1", the correct call to TasteHit's API would be:

1
POST https://www.tastehit.com/api/{customer}/v1/interaction/bob/item1/visit

Once this call is done once, it becomes possible to request recommendations for user bob. If no errors were encountered, TasteHit will respond with a status-code 204, and no content.

Possible errors:

  • A 400 error code will be returned if no item in your catalog has the specified Unique ID.
  • A 400 error code will be returned if the action you provided is not one of the allowed values.
  • A 429 error code will be returned if you send too many requests in one second.

Receiving data

The following paragraphs describe how you can retrieve product selections in JSON format from the TasteHit API.

Statistic-based algorithms

To receive recommendations from the TasteHit API, an algorithm/widgetID has to be set up. The name of the algorithm is a required parameter for the API call.

Let us pretend that we configured an algorithm/widgetID called "popular" (described here), which doesn't depend on a specific user. It returns the most popular products in the last 365 days:

1
GET https://www.tastehit.com/api/{customer}/v1/popular/r

No further parameters are necessary for returning the most popular products.

Here is an example of a possible API response:

1
2
3
> [{"item_pid":"5519","score":1999},{"item_pid":"5453","score":1749},
{"item_pid":"5507","score":1431},{"item_pid":"5510","score":1040},
{"item_pid":"5455","score":1015}]

In this particular case, the "score" is the number of times the recommended products have been visited in the last 365 days. The Unique IDs of returned products can then be used (in your backend or frontend code) using your own local version of the product catalog. Unique product IDs have to correspond between your local catalog and the catalog version imported by TasteHit in CSV/XML (and configured here).

Personalized-algorithms

For algorithms which depend on a user or product, more parameters need to be sent to the API with each request.

Let us assume that we created a widgetID/algorithm called "personalized1" here and selected the content type "Recommendations". This algorithm expects to receive a unique user identifier, or a Unique product ID, or both. It generates recommendations based on these parameters. The route will return an empty list if none of these parameters is sent:

1
2
GET https://www.tastehit.com/api/{customer}/v1/personalized1/r
> []

user and item identifiers are passed as "query parameter" in the request:

1
2
3
4
GET https://www.tastehit.com/api/{customer}/v1/personalized1/r?item_pid=5519
> [{"item_pid":"4224","score":43.30695122314939},{"item_pid":"232","score":42.417421119403386},
{"item_pid":"1351","score":41.76146465591175},{"item_pid":"3708","score":41.54110231519602},
{"item_pid":"3567","score":40.76555276329761}]
1
2
3
4
GET https://www.tastehit.com/api/{customer}/v1/personalized1/r?user_id=TH-0000288e-54be-1c62-189b-33f88600782f
> [{"item_pid":"5007","score":28.12656487648425},{"item_pid":"4921","score":27.413636576766184},
{"item_pid":"2990","score":25.64989869758979},{"item_pid":"1406","score":25.627659928190972},
{"item_pid":"4496","score":25.337668548584272}]

If a user identifier is sent as a query parameter, recommendations will be tailored to the user. If an item identifier is sent as a query parameter, recommendations will be related to this particular product.

Resorting algorithms

It is also possible to use the API to sort a list of items according to some criterion. To do so, a list of items has to be passed via the "itemarray" parameter. The criterion according to which the items will be sorted and returned has to be given by the "resort" parameter.

The algorithm defined by the algorithm/widgetID will have no effect on the resorting criterion. When the resort parameter is used, TasteHit only uses the widgetID to collect statistics such as the number of API calls per widgetID.

The itemarray has to be a URL-encoded JSON array. For example, in Javascript:

1
2
> encodeURIComponent(JSON.stringify(["item1", "item2", "item3"]))
'%5B%22item1%22%2C%22item2%22%2C%22item3%22%5D'

If we wanted to resort this list of items by popularity (most frequently visited items first), the call would be:

1
2
GET https://www.tastehit.com/api/{customer}/v1/home1/r?resort=popular&itemarray=%5B%22item1%22%2C%22item2%22%2C%22item3%22%5D
> [{"item_pid":"item3","score":1999}, {"item_pid":"item1","score":500}, {"item_pid":"item2","score":300}]

Other possible values for the resorting method are:

  • unpopular: Least frequently visited items come first,
  • foruser: Items most appropriate for a given user come first,
  • random: Items are randomly sorted.

Options

Number or products

By default, the TasteHit API will return 5 recommendations. This behavior can be changed with the limit parameter:

1
2
GET https://www.tastehit.com/api/{customer}/v1/home1/r?limit=1
> [{"item_pid":"5519","score":1999}]
1
2
3
4
5
6
GET https://www.tastehit.com/api/{customer}/v1/home1/r?limit=10
> [{"item_pid":"5519","score":1999},{"item_pid":"5453","score":1749},
{"item_pid":"5507","score":1431},{"item_pid":"5510","score":1040},
{"item_pid":"5455","score":1015},{"item_pid":"4961","score":965},
{"item_pid":"5512","score":933},{"item_pid":"5509","score":906},
{"item_pid":"5541","score":843},{"item_pid":"5447","score":823}]

Pagination

It is possible to implement a pagination system by sending a score with every API request. For example, the first 3 recommendations of a specific configuration (API algorithm/widgetID configuration + filters + user ID) can returned by this request:

1
GET https://www.tastehit.com/api/{customer}/v1/home1/r?limit=3

will be:

1
> [{"item_pid":"5519","score":1999},{"item_pid":"5453","score":1749},{"item_pid":"5507","score":1431}]

It would be possible to return the same 3 recommendations using 3 separate requests:

1
2
GET https://www.tastehit.com/api/{customer}/v1/home1/r?limit=1
> [{"item_pid":"5519","score":1999}]

The first request returns a score of 1999, which we return in the second request:

1
2
GET https://www.tastehit.com/api/{customer}/v1/home1/r?limit=1&pscore=1999
> [{"item_pid":"5453","score":1749}]

This second request returns a score of 1749, which we send back with the third request:

1
2
GET https://www.tastehit.com/api/{customer}/v1/home1/r?limit=1&pscore=1749
> [{"item_pid":"5507","score":1431}]

The pscore parameter is a shortened name for "pagination score".

Filters

Basic configuration

It is possible to restrict the recommendations returned using filters. These filters will be applied using the fields available in the product catalog. These fields have to be defined here beforehand. Let us suppose that the product catalog contains a field called "type", which describes the type of products in the catalog (with possible values such as: "clothing", "sports equipment", "tools", "art"). To request recommendations for products of type "clothing", we will need to create a filters object and pass it to the API. In Javascript:

1
> var f = [{type: 'clothing'}]

This object will need to be encoded before being passed to the route. In Javascript, we would need to do the following:

1
2
> encodeURIComponent(JSON.stringify(f))
'%5B%7B%type%22%3A%clothing%22%7D%5D'

To return the most popular clothing products, the request would look like:

1
GET https://www.tastehit.com/api/{customer}/v1/popular/r?filters=%5B%7B%type%22%3A%clothing%22%7D%5D

There are two types of filters that can be applied to text fields (of type string). For an inclusive filter, the following object will request the API to only return clothing products:

1
[{type: 'clothing'}]

For an exclusive filter, the following object will request the API to NOT return any clothing products:

1
[{type: 'clothing', exclusive: true}]

For numeric fields, it is possible to define a minimum and a maximum. For example, the following filter will only return products that cost more than 10 Euros (the currency depends on the parameters that are set in the catalog, as well as the context language/location, if specified):

1
[{price: {min: 10.0}}]

The following filter will only return products that cost less than 100 Euros:

1
[{price: {max: 100.0}}]

The following filter will only return products whose price is between 10 and 100 Euros:

1
[{price: {min: 10.0, max: 100.0}}]

True/false columns

The configuration of the catalog allows you to define additional boolean properties (true/false) for all products in the catalog. The configuration can be done here in the "Additional columns" section. Let us assume that we created two additional boolean columns: "entertainment", which contains 5 products, and "business", which contains 3 products. It is possible to define filters on these properties. For example, this filter will only return products which are classified as "entertainment":

1
[{entertainment: true}]

This filter can be used in the following request and the resulting query will be:

1
2
3
4
GET https://www.tastehit.com/api/{customer}/v1/popular/r?filters=%5B%7B%entertainment%22%3Atrue%7D%5D
> [{"item_pid":"1273","score":48},{"item_pid":"718","score":37},
{"item_pid":"2492","score":28},{"item_pid":"1598","score":23},
{"item_pid":"2554","score":13}]

In order to exclude "entertainment" products, the filter would be:

1
[{entertainment: false}]

It is also possible to combine filters:

1
[{type: 'clothing', exclusive: true}, {price: {min: 10.0, max: 100.0}}, {business: false}]

In this case, the TasteHit API will only return products which simultaneously fulfil all the rules.

Filters on creation dates

A special field called "createdAt" is automatically generated by TasteHit for each product when the product appears in the catalog for the first time. This field contains the creation date of the product, in number of seconds since 1970. In order to create a filter which only returns products that were added to the catalog during the last 5 days, the following code would have to be used in Javascript:

1
2
3
4
> var d = new Date();
> var a = [{createdAt: {min: d.getTime()/1000 - 5*24*3600 }}]
> encodeURIComponent(JSON.stringify(a))
'%5B%7B%22createdAt%22%3A%7B%22min%22%3A1460736803.993%7D%7D%5D

And the API request would be:

1
GET https://www.tastehit.com/api/{customer}/v1/home1/r?filters=%5B%7B%22createdAt%22%3A%7B%22min%22%3A1460736803.993%7D%7D%5D

which could return:

1
[{"item_pid":"5689","score":234},{"item_pid":"5195","score":1},{"item_pid":"5695","score":0}]

If we create a filter which only selects products that were created later than the current date, we will not receive any recommendations:

1
2
3
> var b = [{createdAt: {min: d.getTime()/1000}}]
> encodeURIComponent(JSON.stringify(b))
'%5B%7B%22createdAt%22%3A%7B%22min%22%3A1461168803.993%7D%7D%5D'
1
2
https://www.tastehit.com/api/{customer}/v1/home1/r?filters=%5B%7B%22createdAt%22%3A%7B%22min%22%3A1461168803.993%7D%7D%5D
> []

Here is a filter for products created between 3 and 5 days ago:

1
2
3
> var c = [{createdAt: {min: d.getTime()/1000 - 5*24*3600, max: d.getTime()/1000 - 3*24*3600}}]
> encodeURIComponent(JSON.stringify(c))
'%5B%7B%22createdAt%22%3A%7B%22min%22%3A1460736803.993%2C%22max%22%3A1460909603.993%7D%7D%5D
1
2
GET https://www.tastehit.com/api/{customer}/v1/home1/r?filters=%5B%7B%22createdAt%22%3A%7B%22min%22%3A1460736803.993%2C%22max%22%3A1460909603.993%7D%7D%5D
> [{"item_pid":"5689","score":234},{"item_pid":"5195","score":1}]

The possible errors for such requests are:

  • Code 400 will be returned if the specified algorithm/widgetID was not created here.
  • Code 429 will be returned if too many requests were sent per second.

Comments