Apart from the events collected by the recommendation client, the recommendation engine can use external information about the products. This information must be uploaded to the recommendation engine by the administrator of the website.
The following information can be loaded to the recommendation solution:
- Product price - Products cheaper than the specified threshold can be filtered out from recommendations
- Availability timeframe - Certain products are be recommended only in the specified time window
- Custom attributes - You can group recommendations and narrow down the results, for example, to non-food products or to news that are related to the end user's city
The recommendation client provides a REST interface that accepts items in XML format. You can use the interface to post item information within the request's body into the store, and to display or update the items directly.
You can use HTTP methods to create, update or retrieve items that are in the data store.
For getting or posting content data, basic authentication is enabled by default. Use your customer ID and license key as username and password. If authentication is enabled for recommendation requests and you want to change this, contact firstname.lastname@example.org.
Use the GET method to retrieve all information that is stored in the database for the given item ID:
Use the POST request to create or update items with the given ID in the database:
A body of the request must contain a valid XML document. Once uploaded, the item is scheduled to be inserted in the database, and it is not directly available.
Use the DELETE method to delete all information that is related to the given item ID.
The item is scheduled to be removed from the database.
The following call attributes are available:
||Your customer ID, as defined when enabling Personalization (for example, "00000").||alphanumeric|
||A unique ID of the Content item/product. Used to identify the item in the database.||integer|
||An ID of the type of Content item/product. In most cases, the value is 1 but you might have items/products of more than one type.||integer|
||A language code of the Content item/product (for example, "ger-DE"). This parameter is optional.||string|
Request object format¶
An XML representation of the data object used for item import can look like this:
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
XML schema definition
The current schema that is used for interpreting the XML objects can be seen here.
The following keys and attributes used in the XML object are available:
||A unique ID of the item/product. This parameter is required.||integer|
||An ID of the type of item/product. This parameter is required.||integer|
||Additional information about the item.||alphanumeric|
||Currency used for the price. By default, prices are expressed in EUR.||ISO 4217|
||The item's price in the currency's fractional units (for example, cents).
See below for more information.
If NULL or not available, the item is considered valid immediately.
See below for more information.
If NULL or not available, the item is considered valid indefinitely.
See below for more information.
||A logical (website) navigation path through which the end user can reach the item/product in your website.
You can define multiple paths for the product.
|alphanumeric, separated with "/" ("%2F") characters|
Keys and their values can only contain letters, digits and underscore characters. Attribute keys are case-sensitive.
If the currency does not have a fractional unit, the main unit is used, for example 12 for 12 Japanese Yen. To check whether the currency has fractional units, see the ISO 4217 standard.
Items with defined validity are recommended only in the specified timeframe.
Values in the
validfrom attributes must follow the XSD format and do not include the time zone.
Time zone is always your time zone.
With the data import interface, you can upload information about the paths to categories in which the product is located. However, the category path can be also updated as a result of the "Click" events. If you regularly upload product data, the "Click" event cannot contain the category path information. Otherwise, the following negative side effects occur:
- Every new category path attached to the "Click" event is appended to a list of the categories of the product
- Imported product data overwrites the collected category paths
For example, when a product that is originally located under
Garden is clicked in the "Hot Sellers" section, the category path
TopSeller is sent.
Content items/products with no attributes¶
All the elements and attributes except the
id are optional.
You can therefore upload a product without any additional information.
You do it, for example, when a random recommendation model is used
or you want to want to apply ad-hoc boosting and filtering of recommendations.
As a result, the recommendation engine randomly recommends the imported items/products.
This can prove useful for a news agency, where new items are published very often.
You can upload any data under the
<content> key of the XML object.
This data is used in full-text analysis models only.
You can also define custom attributes under the
This section can only contain values that are distinct and used to build pre-filtered models.
By default, it is assumed that every attribute is of type "NOMINAL", which means that there is a limited set of values, and values of an attribute are treated as distinct when calculating the results of a content-based model.
If you have an attribute that is of type "NUMERIC", and you add another attribute of the same type, the recommendation engine treats the two values as a range.
However, if the other attribute is of type "NOMINAL", they are both treated as different and have no "distance-based similarity".
Another typical example of a custom attribute is the color of an item.
To upload the value to the data store, add the following line under the
You can have multiple attributes with the same name and different type.
size can be expressed as a number (40.5) or as a code ("L").
HTTP response codes¶
The following HTTP response codes are used by the recommendation controller:
|HTTP Status Code||Description|
|200 OK||The GET request was processed successfully.|
|202 Accepted||The POST or DELETE request was processed successfully.|
|400 Bad Request||Wrong request formatting. The XML content cannot be validated.|
|404 Not Found||The element requested by the GET or DELETE request was not found.|
Transferring item identifiers¶
You could use the data import interface to help migrate the database, when it involves changing item IDs of items that are supported by the recommendation engine. If you transfer items from one ID to another, you can use the events recorded for "old" item IDs to calculate model results that present "new" IDs.
Use the following method to pass the XML object:
1 2 3 4 5 6
All related historical user data is rewritten to point to the new item. The old item is wiped, including all attributes.
The attributes of the "old" item ID are not moved or merged, and if you rely on attributes, for example, for filtering based on prices, you must reimport the new item.