Child pages
  • 2b. Fetching Recommendations V2
Skip to end of metadata
Go to start of metadata

Recommendation request V2

Extended version of the recommendation request described in 2.Fetching Recommendations.

Attention: This call does not support XML format. Only JSON and JSONP are avaliable.


Query String Parameters

NameExample Default
numrecs"20"Number of recommendations to fetch10
Comma separated list of context items or/and user history codes. Multiple attributes allowed. If a URL is used as item ID (very special seldom configuration), one must define multiple attributes instead of comma separated list.Depends on the model. Usually CLICKED.
outputtypeid 1Required, if the scenario defined multiple output item types, otherwise it is optional.Lowerst output type supported by the scenario.
categorypath"Men/Shirts"Category to fetch recommendations for. The result depends on the scenario configuration.whole shop
attribute (new) "title", "color"Attribute key(s) to add in the response attributes list. It allows pure clientbased recommendations without requesting local customer data. An import or enriched tracking of items is required to feed the recommender with this information. Multiple attributes are allowed, e.g. &attribute=title&attribute=vendor or a csv listempty list
Function or method name for a JSONP request."jsonpCallback"
<any attribute key>
(for example "color") 

Is used, if a submodel with the same name and value is configured. See Submodel configuration for more information.

Example: ...&color=red

submodels are not used
userattributeattributename of a user, e.g. "gender" or "customerclass"

If defined, the recommender tries to find the attribute value for the current user and - if available - prefers recommendations which are typically used by the current user's gender.

Examples would be:

  • If the user is female, do not recommend products that are for males or 
  • if the customerclass is "high value customer", recommend high-priced products

It requires a user attribute import and a valid submodel configuration. Please contact for questions or detailed information.

a csvlist of user attribute keys

e.g. userattribute=gender,customerclass

usecontextcategorypathtrueIf 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.
recommendCategory trueIf 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 "Sport/Football" and "America/USA". Depending on the category it is shown with a football field or the USA flag in the webpage 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 "closer" category found.



The response is more powerful in comparison to the V1 of the recommendation response. New features are:

  • Better presentation of the origin context of the recommendation.
  • Amount of viewers of the context items is provided. One can for example put the information next to the current viewed product/article as "currently read by 10 visitors".
  • The possibility to return additional attributes to the recommended item. One can use it to render the recommendation in JavaScript without backend development
  • A clickrecommended URL is included, which should be used if a recommendation was clicked
  • A rendered URL which should be used if a recommendation was shown on the webpage

  "contextItems": [ // information about the request's contextitem(s)
      "viewers": 134, // amount of users that were looking on this item 
      "itemType" : 1,
      "itemId" : 10,
      "sources" : "REQUEST"
      "viewers": 79,
      "itemType" : 1,
      "itemId" : 11,
      "sources" : "REQUEST" 
  "recommendationItems": [
      "relevance": 23,
      "itemType": 1,
      "itemId": 100175717,
	  "origin": {
        "itemIds" : [10, 11], // these are the items that the recommendations are based on (context or user history items), multiple values are possible
        "itemType" : 1,
        "source" : "REQUEST" // Possible options: REQUEST (parameter "contextitems") or CLICK, CONSUME, BUY, BASKET, RATE (user history)
      "category" : "Men/Shirts", // Provided only, if category suggestion is requested
      "links" : {
         "clickRecommended" : "//", // provided, if a user ID is available
         "rendered" : "//"
      "attributes" : [  // only values that were requested in the query string are provided
 		 {	"key": "title", 
			"value": [
				"French Cuff Cotton Twill Oxford"
		}, ...
      "relevance": 22,
      "itemType": 1,
      "itemId": 100172819,
      "origin": {
        "itemIds" : [10, 11], 
        "itemType" : 1,
        "source" : "REQUEST"
  • No labels