API Documentation

This document describes how to use the TasteHit API. It is intended for developers. You need to Sign Up in order to use the API or insert widgets in your shop.

Two paradigms

There are two ways of using TasteHit's recommendations engine in your online shop:

  1. By inserting graphical widgets in your pages. You can configure your widgets (graphics, algorithms, filters) here (login required). To place a widget on a page of your online shop you just need to insert an HTML <div> element. TasteHit takes care of the graphical rendering of the widgets.
  2. By calling TasteHit's HTTP-based recommendation API. TasteHit will return a list of recommendations in JSON format. You will have to take care of the graphical rendering yourself.
The first method is usually the easiest way to integrate TasteHit recommendations, and this is indeed what most shops use. However, TasteHit's API might provide more flexibility in some cases e.g. you want to build a category page where the order in which products are displayed is based on the visitor's browsing history and maximize his chances of conversion.

This page describes how to use TasteHit's API. The API is HTTP-based, so it is accessible from your browser, or using using a tool such as curl. All major programming languages have libraries for accessing HTTP-based APIs.

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


As described in our FAQ, TasteHit generates recommendations 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:
    POST http://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:
    GET http://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

Name Description Type

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

E.g. iOB04Fe--aml7Q


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.


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") en JavaScript).

  • In interaction requests (POST), this is the item with which the user interacted.
    • /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.
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 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.
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

(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.

floating-point number

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


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)

Notify TasteHit of an interaction

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:

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:
POST http://www.tastehit.com/api/CustomerX/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.

Replace XXXX with your TasteHit Customer ID, which can be found in the "Your Profile" part of the dashboard.

Possible errors:

  • A 400 error code will 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.

Getting recommendations in JSON format

Popular products

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" (configured here). It returns the most popular products in the last 365 days:

GET http://www.tastehit.com/api/CustomerX/v1/popular/r 
No further parameters are necessary for returning the most popular products.

Here is an example of a possible API response:

> [{"item_pid":"5519","score":1999},{"item_pid":"5453","score":1749},
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 recommendations, or recommendations related to a specific product

Let us assume that we created a widgetID/algorithm called "personalized1" ici 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:
GET https://www.tastehit.com/api/CustomerX/v1/personalized1/r
> []
user and item identifiers are passed as "query parameter" in the request:
GET https://www.tastehit.com/api/CustomerX/v1/personalized1/r?item_pid=5519
> [{"item_pid":"4224","score":43.30695122314939},{"item_pid":"232","score":42.417421119403386},
GET https://www.tastehit.com/api/CustomerX/v1/personalized1/r?user_id=TH-0000288e-54be-1c62-189b-33f88600782f
> [{"item_pid":"5007","score":28.12656487648425},{"item_pid":"4921","score":27.413636576766184},
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.

Defining the number of recommendations to be returned

By default, the TasteHit API will return 5 recommendations. This behavior can be changed with the limit parameter:
GET https://www.tastehit.com/api/CustomerX/v1/home1/r?limit=1
> [{"item_pid":"5519","score":1999}]
GET https://www.tastehit.com/api/CustomerX/v1/home1/r?limit=10
> [{"item_pid":"5519","score":1999},{"item_pid":"5453","score":1749},


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:
GET https://www.tastehit.com/api/CustomerX/v1/home1/r?limit=3
will be:
> [{"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:
GET https://www.tastehit.com/api/CustomerX/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:
GET https://www.tastehit.com/api/CustomerX/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:
GET https://www.tastehit.com/api/CustomerX/v1/home1/r?limit=1&pscore=1749
> [{"item_pid":"5507","score":1431}]
The pscore parameter is a shortened name for "pagination score".


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:
> 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:
> encodeURIComponent(JSON.stringify(f))
To return the most popular clothing products, the request would look like:
GET https://www.tastehit.com/api/CustomerX/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:
[{type: 'clothing'}]
For an exclusive filter, the following object will request the API to NOT return any clothing products:
[{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):
[{price: {min: 10.0}}]
The following filter will only return products that cost less than 100 Euros:
[{price: {max: 100.0}}]
The following filter will only return products whose price is between 10 and 100 Euros:
[{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":
[{entertainment: true}]
This filter can be used in the following request and the resulting query will be:
GET https://www.tastehit.com/api/CustomerX/v1/popular/r?filters=%5B%7B%entertainment%22%3Atrue%7D%5D
> [{"item_pid":"1273","score":48},{"item_pid":"718","score":37},
In order to exclude "entertainment" products, the filter would be:
[{entertainment: false}]
It is also possible to combine filters:
[{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:
> var d = new Date();
> var a = [{createdAt: {min: d.getTime()/1000 - 5*24*3600 }}]
> encodeURIComponent(JSON.stringify(a))
And the API request would be:
GET https://www.tastehit.com/api/CustomerX/v1/home1/r?filters=%5B%7B%22createdAt%22%3A%7B%22min%22%3A1460736803.993%7D%7D%5D
retournerait par example:
If we create a filter which only selects products that were created later than the current date, we will not receive any recommendations:
> var b = [{createdAt: {min: d.getTime()/1000}}]
> encodeURIComponent(JSON.stringify(b))
> []
Here is a filter for products created between 3 and 5 days ago:
> var c = [{createdAt: {min: d.getTime()/1000 - 5*24*3600, max: d.getTime()/1000 - 3*24*3600}}]
> encodeURIComponent(JSON.stringify(c))
GET https://www.tastehit.com/api/CustomerX/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.


We will white-list your servers' IP addresses, so that only requests coming from your servers will be accepted and processed by TasteHit.

You will be limited to 10 requests per second. If more than 10 requests per second are sent, TasteHit will return an error with code 429. If this limit is too low, please contact us and we will increase it.