This way of fetching recommendations is deprecated, please use 2b. Fetching Recommendations V2
This page describes how to fetch recommendations from the Recommender System via recommendation requests. Before recommendation can be fetched from the recommendation controller, it is required that sufficient amount of events were collected and the model build has finished successfully.
BASIC Authentication for fetching recommendations is enabled for some configurations (for example for Gambio Plugin) by default. Use the customerid as username and the license key as password. The license key is displayed in the upper right in the Admin GUI (https://admin.yoochoose.net) after logging with your registration credentials.
If you plan to use JSONP , the authentication must be disabled. If it is enabled in your solution (can be easily tested with a recommendation request in a browser), please contact the eZ Recommender support (firstname.lastname@example.org) for further information and disabling.
Recommendations are retrieved from the recommendation engine via RESTful-Requests using the GET method. The result is a list of item IDs that can be used to call the underlying CMS or shop system in order to retrieve the necessary information for the rendering process.
To allow the customer to retrieve different types of recommendations based on different methods (e.g. Collaborative Filtering, Content Based, Stereotype, etc.) the Recommendation System uses scenario IDs relating to a predefined set of configurations inside the system. These configurations are a combination of methods and filters that should be applied including possible fallbacks if the requested methods do not deliver a result. See User Guide for more information about scenario configuration.
A recommendation request looks as followed:
The embedded parameter "solutionid", "clientid" and "userid" are the same as user for event tracking. Additional embedded parameters are described in the following table.
|scenarioid||The ID of the scenario used for providing recommendations. It is configured or predefined in the Administration GUI.||alphanumeric|
|extension||The format, the server generates the response in. There are three formats supported: JSON, XML and JSONP. See the chapter "Response Format" below in this document for more information||json, xml or jsonp|
Basic Request Parameters
Using additional query string parameters one can customise the recommendation request.
|numrecs||Defines the amount of recommendations that should be delivered. Keep this amount as low as possible as this increases the response time of the recommendation call.||1 to 50 |
(required for context based recommendations)
|Comma-separated list of items that the user is currently viewing on the web page. All items must be from the same type. The type is defined in the scenario configuration.||comma separated list of item IDs (1 to 2147483647)|
A single item to be used as a source for creating recommendations.
|1 to 2147483647|
(required, if the scenario defined multiple output item types, otherwise it is optional)
Item type of the requested recommendations. This can differ from the input item type, e.g. if you want to get recommendations for pictures based on a given article the item type for pictures has to be used here. For a web shop this is probably not needed as only one type of items is tracked.
Multiple item types are available only for advanced license.
|categorypath||Base category path for providing recommendations. The format is the same like the category path for the event tracking. |
It is possible to add this parameter multiple times. The order of recommendations from the different categories is defined by the calculated relevance.
(used only for JSONP request)
|Function or method name for a JSONP request. It can be a function ("callme"), or a method ("obj.callme").|
(by default "jsonpCallback")
An example of the recommendation request:
It fetches 8 recommendations for user Mustermann, who is watching the item 123 and the category "/Camera/Compact" from the scenario with the identifier productpage.
See the section "Advanced Request Parameter" below in this document for advanced features.See the section "Integration best Practices" below in this document for the implementation examples.
The recommendation request returns a list of item IDs that are JSON, JSONP or XML formatted. The result can be easily integrated into any web-page by using some lines of script code.
See Ten Minutes Guide  for a simple example written in PHP.
The resommendation result list looks like the following:
The "reason" field string tells the user out of which model the recommendations were provided. The models are a preconfigured by the Recommendation Engine. For example "CF_I2I (context: ITEMS(s))" means that the model which provides the recommendation is "Collaborative Filtering based on an Item to Item similarity" with the given context item as input. The human readable explanation is (in this case "Users who bought this item also bought these items").
The "relevance" defines the similarity to the context item according to internal algorithm and scenario configuration. A higher value stays for a "better" recommendation. The list of recommendations is sorted by the relevance in descending order.
If JSONP format is requested, the response is wrapped in the function call like this:
The Following HTTP response codes are used by the recommendation controller.
HTTP Status Code
Request was successfully processed.
|304 Not Modified||Recommendation result was not modified since the time specified in the provided |
400 Bad Request
The request is wrong formatted. See response body for more information.
Illegal authentication credentials. (huhu)
404 Not Found
The requested element was not found. It can be customer ID (a.k.a. mandator ID), model ID, scenario ID etc.
The combination of used models and given recommendation request parameters doesn't allow to provide recommendations.
This could e.g. if personalized recommendations are requested for a user who has no history at all.
500 Internal Server Error
Unspecified error. Please inform support, if you get this error repeatedly.
The body of the response in case of errors contains human readable error message. The format of error messages can be changed and should not be used for automated processing.
Advanced Request Parameter
There are some additional very special request parameters.
|<any attribute name>|
(used only, if submodels are configured)
Item's attribute, e.g. color, price, etc. These are customer specific and can only be understood by the recommender system if the item attributes are imported by using the YOOCHOOSE content import APIs. There can be multiple attributename and attributevalue pairs.
|usecontextcategorypath||If set to true, the category path of the given contextitem(s) will be resolved by the recommender engine from the internal store and used as base category path. If more than one category is returned, all categories are used for providing recommendations. |
Avoid setting this parameter to true to minimize the response time. Use the parameter categorypath to provide the category to the recommender engine during the request.
|true or false |
(to be used only in the eZ Recommendation extension)
If passed in combination with a "categorypath" value, the "closest" category the recommended items linked with will be delivered in the response as additional field "category".
This feature helps to find "better" template for articles, which are located in several categories.
For example there is an article about the football in the USA. The article is located in both categories "/Spot/Football" and "/America/USA". Depending on the category it is shown with a football field or the USA flag in the background.
If this article recommended and being clicked in the category "/Sport/Cricket" it must be open with the "football" template. If the article is being clicked in the category "/America/Canada" it must be open with the "USA" template.
The category information is returned only, if the article is located in several categories and the "better" category found.
|true or false |
In the most cases the response of the recommendation service can be cached for some time. Depending on the used recommendation model and context it can dramatically reduce the amount of the recommendation request and therefore the price for using the recommendation service. Recommendation service support following HTTP headers to allow cache control on the client side:
|Request||Allows a 304 Not Modified to be returned if content is unchanged.||"HTTP-date" format as defined by RFC 2616 |
|Response||The last modification date of the recommendations.|
|Gives the date/time after which the response is considered to be 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 some scenario configuration changes. The expiration timestamp is a best-effort prediction based on the model building configuration and provided context. The shortest expiration period is 5 minutes from the request time. The longest is 24 hours. In the table below several examples are illustrated:
|Best selling products last 7 days||no context||24 hours||The model with the 7 days scope is usually built once a day. It can be easily cached for 24 hours. It has no context and can therefore be cached globally for all the users of a customer.|
|Also bought products in the 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. It can be cached for every product. The same result can be used for all users of a customer.|
|Also consumed read articles in the last hour||current article||30 minutes||Models with a short scope are ussually build several times a day or even per hour. In this case the expiration time is set to the half of the model build frequency/period.|
|Personalized recommendation based on the user's statistic||customers click history||now||Although the statistic model is not updated within minutes , it is very likely that the context will be changed shortly (customer will click another product and therfore the click is added to his history). The expiration time should not be much longer, than the user activity on the web page.|
In most cases you do not need to calculate the expiration time manually. The table above is provided for the orientation, how the Expires header of the HTTP response is calculated by the recommendation engine and already provided to your caching system. You just need to make sure that the Expires header is used in the configuration of your caching system instead of a static value out of your configuration.
Integration best Practices
There are several ways to integrate the REST calls to the Recommendation engine and avoid the blocking of the web page rendering, if the communication with the Recommender is distrusted or interrupted.
The simplest way to load recommendations is synchronously request the Recommendation Engine for recommendations as it is needed. This way is sufficient in most cases. The most important drawback is the request time of the increases by the time of the recommendation request. If the network is overloaded or the Recommendation Engine is not available it can lock the request.
Loading in the bottom
Non-blocking loading in the background
If the website is implemented in some language which supports multithreading or non-blocking I/O, it is possible to start the recommendation request just after the browser request is received. The page generation and the recommendation requests will be accomplished in parallel. Combining this idea with the previous solution by placing the recommendation results in the bottom of the page one can avoid any interruption in the processing.
Loading over proxy
Alternative approach is creating the HTML code on the server side for every target page in a sense to simplify the script on the client side.
As a possible implementation of such a proxy following tools can be used: the apache proxy module, some independent daemon like “netcat” or a PHP script.
An overview of pros and cons for every technique.
XMLHttpRequest + Proxy
|It is not blocked by ads blockers or no-track plug-ins.|
|Works for server without multithreading functionality.|
|It is compatible with frontend caching on the server.|
|It does not delay the page rendering.||depends||depends|
|It supports authentication for recommendation fetching||depends|
|||Representational state transfer - Wikipedia|
Uniform Resource Identifier (URI): Generic Syntax
JSONP - Wikipedia
|||Apache Module mod_proxy|
Hypertext Transfer Protocol - HTTP/1.1
|||Yoochoose Ten Minutes Guide|