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:

An interaction took place between a visitor and a product. This
information has to be sent to TasteHit.

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

Request recommendations:

1

GEThttps://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}.

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.

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

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

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

GEThttps://www.tastehit.com/api/{customer}/v1/personalized1/r>[]

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

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.

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:

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:

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

>varf=[{type:'clothing'}]

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

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:

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:

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: