Child pages
  • 2a. Fetching Recommendations (deprecated)
Skip to end of metadata
Go to start of metadata

@Deprecated API

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 ( after logging with your registration credentials.

If you plan to use JSONP [3], 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 ( for further information and disabling.

Getting recommendations

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:[solutionid]/[customerid]/[userid]/[scenarioid].[extension]?parameter=value&[attributename=attributevalue]

The embedded parameter "solutionid", "clientid" and "userid" are the same as user for event tracking. Additional embedded parameters are described in the following table. 

Parameter NameDescriptionValues
scenarioidThe ID of the scenario used for providing recommendations. It is configured or predefined in the Administration GUI.alphanumeric 
extensionThe 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 informationjson, xml or jsonp

Basic Request Parameters

Using additional query string parameters one can customise the recommendation request.

Parameter NameDescriptionValues
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
(default "10")
(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. 
This parameter is deprecated. Use "contextitems" instead.

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.

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

legal JavaScript function call

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

Response handling

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 [6] for a simple example written in PHP.

The resommendation result list looks like the following:

Example JSON-response:

{ recommendationResponseList: [ 
  { reason: "CF_I2I (context: ITEMS(s))", 
    itemType: 2, 
    itemId: 1399, 
    relevance: 100 },
  { reason: "POPULARITY_SHORT_BUY (context: ITEMS(s))", 
    itemType: 2, 
    itemId: 4711, 
    relevance: 91 
  } ] } 

Example JSONP-response:

{ recommendationResponseList: [ 
  { reason: "CF_I2I (context: ITEMS(s))", 
    itemType: 2, 
    itemId: 1399, 
    relevance: 100 },
  { reason: "POPULARITY_SHORT_BUY (context: ITEMS(s))", 
    itemType: 2, 
    itemId: 4711, 
    relevance: 91 
  } ] })

Example XML-response:

  <reason>POPULARITY_SHORT_BUY (context: ITEMS(s))</reason>

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:

Response Codes

The Following HTTP response codes are used by the recommendation controller.

HTTP Status Code


200 OK

Request was successfully processed.

304 Not ModifiedRecommendation result was not modified since the time specified in the provided If-Modified-Since header

400 Bad Request
414 Request-URI Too Long

The request is wrong formatted. See response body for more information.

401 Unauthorized

Illegal authentication credentials. (huhu)

403 Forbidden

Access denied.

404 Not Found

The requested element was not found. It can be customer ID (a.k.a. mandator ID), model ID, scenario ID etc.

409 Conflict

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.

Parameter NameDescriptionValues
<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.

3a. Data Import, Items and Submodel configuration is required for taking an advantage from this parameter.

usecontextcategorypathIf 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
(default "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".

recommendationResponseList: [ {
		itemId: 1007640000,
		category: "09/0901/090113", ... } ... ]

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
(default "false")

Recommendation Caching

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:

Scope  ExampleFormat
RequestIf-Modified-SinceAllows a 304 Not Modified to be returned if content is unchanged.If-Modified-Since: Sat, 29 Oct 2013 19:43:31 GMT "HTTP-date" format as defined by RFC 2616  [5] 
ResponseLast-ModifiedThe last modification date of the recommendations.Last-Modified: Tue, 15 Nov 2013 12:45:26 GMT
ExpiresGives the date/time after which the response is considered to be outdated
Expires: Thu, 01 Dec 2013 16:00:00 GMT

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:

ModelContextExpiration timeDescription
Best selling products last 7 daysno context24 hoursThe 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 monthcurrent product24 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 hourcurrent article30 minutesModels 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 statisticcustomers click historynowAlthough 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.

Straight Way

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

One can place the code that loads the data from the eZ Recommender on the bottom of the generated document and flush the output buffer to the client just before requesting recommendations. The browser will get a whole page to render and can display it even, if the very end of the page is still loading. Then the Javascript code with the recommendation information included loaded in the bottom of the page must fill the gaps on the page with recommendation as soon as it is completely loaded.

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 from Javascript üsing JSONP

It is not possible to request the recommendation controller server directly from the javascript (over AJAX library or directly over XMLHttpRequest) because of the cross-domain restriction in most browsers. One of the possible technique to work around this limitation is JSONP [3].

Loading over proxy

A better solution in comparison to JSONP is to provide the proxy on the server side, which will forward script requests to the Recommender system. It can be implemented as a very simple proxy using the mod_proxy module [4] of Apache Webserver. It just transfers the data and the javascript renders the response into HTML itself.

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.

Straight Way
Bottom Loading
Background loading
XMLHttpRequest + Proxy
It is not blocked by ads blockers or no-track plug-ins.(tick)(tick)(tick) (tick)
It works, if JavaScript is disabled.(tick)depends   
Works for server without multithreading functionality.(tick)(tick) (tick)(tick)
It is compatible with frontend caching on the server.   (tick)(tick)
It does not delay the page rendering. dependsdepends(tick)(tick)
It supports authentication for recommendation fetching(tick)(tick)(tick) depends


[1] Representational state transfer - Wikipedia

Uniform Resource Identifier (URI): Generic Syntax 


JSONP - Wikipedia 

[4]Apache Module mod_proxy

Hypertext Transfer Protocol - HTTP/1.1

[6]Yoochoose Ten Minutes Guide
  • No labels