Recommendations are retrieved from the recommendation engine with RESTful requests that rely on the HTTP GET method. The result can a list of item IDs that can then be used to call the underlying CMS or shop system and postload the necessary information for the rendering process.
For fetching recommendations, authentication is disabled by default, and it must be disabled when you use JSONP for response handling. If authentication is enabled for recommendation requests and you want to change this, contact firstname.lastname@example.org.
The request for recommendations uses the following pattern:
For the request to return recommendations, you must provide the following parameters:
||Your customer ID, as defined when enabling Personalization (for example, "00000").||alphanumeric|
||An ID of the tracked user in the website (for example, an internal customer code, a session code or a cookie for anonymous users.||alphanumeric|
||An ID of the scenario used for providing recommendations, as defined in the Back Office.||alphanumeric|
||A format of the response (either JSON or JSONP).||
Parameter encoding limitations
All parameters must be URL-encoded (see RFC 3986) and cannot contain a backslash (
Customizing the recommendation request¶
You can customize the recommendation request by using additional query string parameters. For example, you can send the following request to the recommendation engine:
GET https://reco.yoochoose.net/api/v2/00000/john.doe/landing_page.json ?contextitems=123&categorypath=%2FCamera%2FCompact&attribute=title&attribute=deeplink,description&numrecs=8
The request fetches 8 recommendations for user ID
john.doe, who is viewing item 123
and the category
/Camera/Compact, based on the scenario with the identifier
The recommendation response uses the JSON format and should include values of
You can use the following parameters to customize a request:
||20||Defines a number of recommendations to be delivered. The lower this value, the shorter the response time. The default value is 10.||1 to 50|
||10,13,14 or "CLICKED"||A comma-separated list of items that the user is viewing on the web page. The list is required by context-based recommendations. All items must be of the same type. The type is defined in the scenario configuration. If history code is used ("CLICKED","CONSUMED", "OWNS", "RATED" or "BASKET"), context items are pulled from the user profile (for example, the most recent clicks or purchases). This parameter is optional.||1 to 2147483647 (or alphanumeric if enabled)|
||1||Required for scenarios that are defined with multiple output item types, otherwise optional. By default it is the first/lowest output type enabled in the scenario config.||numeric|
||"title" or "description"||If you apply this parameter, the engine tries to fetch the value of the attribute. For example,
||Category path for fetching recommendations. The format is the same as the category path used in event tracking. Add this parameter multiple times to get recommendations from multiple categories. The order of recommendations from different categories is defined by the calculated relevance. The default value is
||Used in conjunction with
||Used in conjunction with
For example, take an article about American football. The article is categorized as
If your recommendation model uses submodels to group content items/products based on an attribute, you can pass the following parameters to request recommendations for a specific group. For more information, see Submodels.
||Applicable if a submodel with the same name and value is configured.||string|
||gender||If defined, the recommendation engine tries to find the attribute value for the current user and, if found, "prefers" recommendations that are typically followed by users with the same value of the attribute. The default value is null.||string, csv list|
The recommendation request returns information about the currently used context items and an array of recommendation objects in JSON or JSONP format. The result can be integrated into any webpage on the client side by using script code. To track user actions like "clickrecommended" and "rendered", use the links delivered in the response. For more information, see inline comments below.
You can preview the actual responses that come from the recommendation engine and how they are rendered in the user interface. For more information, see Scenarios.
For more information about integrating recommendations in the web page, see Best practices.
Response object format¶
A JSON response 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 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53
A JSONP response can look like this (same comments apply):
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 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52
HTTP response codes¶
The following HTTP response codes are used by the recommendation controller:
|HTTP Status Code||Description|
|200 OK||Request was processed successfully.|
|304 Not Modified||Recommendation result was not modified since the time specified in the provided
|400 Bad Request414 Request-URI Too Long||Wrong request formatting. See response body for more information.|
|401 Unauthorized||Invalid authentication credentials.|
|403 Forbidden||Access denied.|
|404 Not Found||The requested element was not found. It could be customer ID (or "mandator ID"), model ID, or scenario ID.|
|409 Conflict||The requested combination of models and recommendation parameters cannot return recommendations. This could happen, for example, if you request personalized recommendations for a user who has no history.|
|500 Internal Server Error||Unspecified error. Contact Ibexa support if this error is recurring.|
In case of errors, the response body contains human-readable error messages. Error messages can change, do not use them for automated processing.
If data import with the Content API was successful, you can also fetch data used for rendering (for example "title", "description" or "deeplink") from the recommendation response.
In most cases the recommendation engine's response can be cached. Depending on the recommendation model and context, it can drastically reduce the number of recommendation requests. The recommendation service supports the following HTTP headers to enable cache control on the client side (all date values must follow the "HTTP-date" format as defined by RFC 2616):
||Enables returning the 304 Not Modified code if content is unchanged.||
||The last modification date of the recommendations.||
||Gives the date/time after which the response is outdated||
The last modification timestamp indicates a change that could influence the recommendation response. It depends on an updated recommendation calculation, an update of an item or certain scenario configuration changes.
The expiration timestamp is a best-effort prediction based on the model configuration and provided context. The shortest expiration period is 5 minutes from the request time, the longest is 24 hours.
In most cases you do not have to calculate the expiration time manually.
Instead, make sure that the
Expires header is used in the configuration
of your caching system and not a static value out of your configuration.
To learn how recommendation engine calculates the
Expires header that is provided
to your caching system, see the following table with caching strategy examples:
|Bestselling products (last 7 days)||No context||24 hours||The model with the 7 days scope is usually built once a day. You can cache its results for 24 hours. It has no context, therefore it can be cached globally for all the users of the site.|
|Also bought products (last month)||Current product||24 hours||The model with the 30 days scope is usually built once a day. The context is always the same, therefore it can be cached for every product, and the same result can be used for all users of the site.|
|Also consumed articles (last hour)||Current article||30 minutes||Models with a short scope are usually built several times a day or even per hour. The expiration time is set to half of the model build frequency.|
|Personalized recommendation based on the user's statistic||User's click history||Now||Statistical models are not updated within minutes, and it is very likely that the context will change shortly (a user clicks another product, the click is added to their history). The expiration time should not be much longer than the user's activity on the web page.|