Recommendation Server API

The recommendation server API creates a request to a recommendations server. The request contains parameters that describe a recommendation’s properties.

Response to the request contains recommendations. Recommendations are a list of results that satisfy the merchandising definition as applied to documents (and other entities).


Documentation is also available at this URL.



XSD Schema

XSD schema is also available at this URL.



API Path

RS Address Parameters

Parameter NameDescription
<REC_SERVER_ADDR>Recommendations server address (see environment page for recommendation server address)
<PORT>Port recommendation server is listening on. Currently 80 or 443. <br> NOTE: use 80 for HTTP requests, and 443 for HTTPS requests.
<VERSION>API version. Currently only ’1’ is supported
<SITE>Customer site name

API Parameters

Parameter NameValueComments
urlURLContext document entity ID. Used to order candidates "best" first, and for filtering candidates for selection. May be multi-valued: "…&url=URL1&url=URL2&…". Only one "url" or "ProductId" should be used.

An alias for "", see "." below.
ProductIDproduct idContext product entity id. Used to order candidates "best" first, and for filtering candidates for selection. May be multi-valued: "…&ProductId=URL1&ProductId=URL2&…". Only one "url" or "ProductId" should be used.

At this time productId’s are converted to urls, and added to the list of urls.

An alias for "", see "." below.
UserIdbnuidUser id for the user making the call. It is the value in bn_u cookie.
. User. Product.Dynamic attribute value that will overwrite whatever is persisted in the data store for that context attribute."Dynamic Attributes" feature provides a way to overwrite whatever is known (or not known) about a particular context attribute. Be it Product attribute, User attribute or attribute of some other entity.

- In Thor you specify a dynamic attribute value instead of specifying a filter on the API call. You must create a filter in VUE that will reference the attribute so that the system recognizes the dynamic attribute.
- To specify product entity attributes, use the following format:
pageTemplatepage template nameUsed to group a number of widgets together.
widgetwidget nameWidgets allow you to specify a recommendation type and recommendation constraints (filters, pins, etc.).

Note: Direct widget calls give you more flexibility (compared to page template or automatic routing calls) at the expense of complexity. See Tracking Data Quick Setup for details.
attrsRecommendable entity’s attributes to include in reply. May be either canonical or catalog.For each recommended entity, the response will include the entity’s ID attribute, plus any attributes named by the attrs parameter. The attribute names may be either canonical or catalog names. The response uses the same name, in the same case, as specified by the attrs parameter. Use "*" to request that all attributes be returned.

To request multiple attributes, use the attrs parameter multiple times: attrs=attribute1&attrs=attribute2&…
queryQuery string for TermGuideIndividual query terms are separated by "+", for example: "query=duct+tape". If you specify query terms other than null, the system ignores all other contexts (url, productid) as well as configured widget objectives, and uses TermGuide instead. See Term Based Recommendations documentation to understand how to configure and use TermGuide.
sourcelocation of the page from where the RS request is generatedDenotes the source of the rest recommendation server call made, and includes the location of the page as its value. The system uses this parameter for routing.
Used only when routing is needed and is ignored for every other call.
- When routing is triggered, routing uses the source parameter value as the routing context.
- When routing is triggered, URL context is ignored.
- When routing is triggered and source is not present, the URL parameter is used for routing. (URL should be treated as source)
- When routing is triggered and source is not present and there are multiple URL parameters present, first URL parameter is treated as the source for routing.
- When routing is triggered and both source and URL parameters are not present, no recommendations will be served.
visitstrailBrowsing history in the form of CSV of URLsUsed to pass the browsing history of the user to the recommendation server. The system takes what you pass in and echoes it back to the caller from the "Last Viewed" Recommendation Type. That is, given recommendations are driven by a widget that is configured to use "Last Viewed" RT. visitstrail will be ignored otherwise.

If the user visited URLs 1, 2, 3, 4 (4 being the last one) then:
- visitsrail (input): 4, 3, 2, 1
- Last Viewed (output): 4, 3, 2, 1

Supported Formats
- …&visitstrail=url1,url2,urls3…
- …&visitstrail=url1&visitstrail=url2&visitstrail=url3…
- …&visitstrail=url1&visitstrail=url2,url3…

See more details at Design and Specification of ’visitsrail’ parameter
pagetypepage type needed for routingUsed to pass page type for routing. For exam Home, Cart, ProductDetail. This can be used in association with the source to pick the correct PT. Only that PT will be picked whose page type matches with the supplied value is this param while evaluating the rules. If not present the first PT found after a rule is satisfied is picked.
formatXML or jsonUsed to specify the format of the response: either XML, or json. Used as an alternative to using the HTTP "Accept" header.

Request Defined Attributes

User, Context/Product/Document, and Request Entity Types

We currently support three primary entity’s whose attributes can be defined as part of the request: User, Context/Product/Document, and Request. However, there is currently no validation; the request can define any attribute it chooses. If the request includes “Dermot.Mee=awesome”, the request context will include an entity “Dermot” whose attribute “Mee”

We currently do not really support Product and Document, but only Context entity type. Context will become an alias for either Product or Document. If the parameter “url” is present, then Context is an alias for Document. If the parameter “productId” is present, then Context is an alias for “Product”.

Binding Entity’s Attributes to Values

Use <Entity>.<attributeName>=<value> to define the entity’s attribute value in the request. For example, “User.ext_uid=E123” or “ Note: The <Entity> name and following dot will soon be mandatory for binding a value to an attribute. But, for a short time, “bare” names without an entity name will continue to be supported. See “Transition” below.

When the entity’s id is defined in the request, the corresponding entity is loaded from the entity store, defining values for all the entity’s attributes. Any entity attributes defined by the request will override the value from the store. The  API parameter value is bound to the attribute, and the one from store is ignored. If no entity id is defined in the request, then the entity’s attribute values are defined only by those specified within the request.

If both internal and external user Id is specified, internal user id is ignored.

Currently, we do not support specifying the product and document id’s using the full names Product.Id or Document.Url. This will be coming. The “old” parameters “ProductId” and “Url” must be used instead.

Examples of defining entity attribute values in the request:

User.cmnState=CaliforniaDefines the User entities’ attribute cmnState to have the value "California". Will be passed to the XPU to make better selections, and can be used in filters
Request.Luxury=trueDefines the User entities’ attribute cmnState to have the value "California". Can be used in normal filters, and as the antecedent of a conditional filter for rules based targetting. "Request.Luxury implies price > 200".

Defining Mutli-valued Attributes

To define a multi valued attribute, repeat the binding multiple times. For example,


will bind Product.Color to the value {red,blue,green}.

Use the “standard” CSV of using double quotes to quote text that should not be broken into multiple values. Double quotes within quoted text will be doubled. For example, the text This text, with commas and quotes, “should” not be broken up would be represented as “This text, with commas and quotes, “”should”” not be broken up”.

User External ID

To specify external user ID to REST API use site specific external user Id attribute name using <User>.<attributeName>

there will be only one way to specify external user id to REST API as parameter.

Parameter NameValueComments
User. For e.g.User.ext_uidexternal user idUser before DOT indicates Entity User and uid for external user ID attribute as named for the site in configuration.

- The parameter name is case insensitive (i.e. User.ext_uid is same as USER.EXT_UID)
- The value of external user ID is case sensitive. (i.e. User.ext_uid=e123 is NOT same as User.ext_uid=E123 ) MAG-115 - Ensure that RS treats external user id value as case insensitive
- Here ext_uid is just example external user id attribute name configured in Entity Config for this site. it can be different for each site.

Note: User.ext_uid is just an example for external User ID attribute name, it can be different for each site. Refer Thor Entity Config CLT for site to find actual name of the external User Id instead of using ext_uid.


For some time, all parameters without an entity name will be also bound to Context.AttributeName. They will also be bound to Request.AttributeName, if Request.AttributeName has not been bound in the request.

Usage Example with Widget*

Response Format

RS supports both XML and JSON response. Following is an example in XML format.

 The recommendation format is as following:

        <displayName>Widget Display Name</displayName>
        <placeholderName>HTML DIV ID</placeholderName>
        <slotResults slot="1" affinity="false" rank="1" scanTime="1">
        <testName>Sample Test Name</testName>
        <variantName>Variant B</variantName>
        <Entity xsi:type="Product">
        <Entity xsi:type="Document">
                <values>P2136_MATE 90558 N DHT ORG</values>

Output Explanation

Element NameSignificance
recResultRoot-level element. A single complete response that contains all of the results.
responseIdUnique identifier of the response
merchModelMerchModel checkpoint id of the MerchModel for which this response is generated.
trackingDatatrackingData is an opaque base 64 encoded string token which is used to decode all meta information about recommendations like widget info, test info, slot info and page info. It is generated using all this info and then encoding it. This element is important in genera,l and more important from an AB test perspective. The test info from the tracking data is used for analysis by the Data Science team.
typeIndicates if the response is for a widget or a page template. Allowed values - widget or pageTemplate
IdWidget name or the page template name associated with the response
widgetResultsTop level element for containing all the results associated with one widget. A response can have multiple widgetResults when the type is "pageTemplate" or request is made for multiple widgets.

For information on elements found within the widgetResults element, see Elements Within widgetResults.
abTestTop level element that contains all information about the ab test i.e Id, testname, variant name and merchModel
contextTop level element that contains information about the context present in the request. Contains information about single or multiple contexts.

For information on elements contained within the context element, see the Elements within Context table.
affinityA dynamic attribute used by filters to determine which item to evaluate first. For more information on the affinity attribute, see Affinity.

Elements Within widgetResults

Elements NameSignificance
IdUnique widget name
displayNameCustomers will see this on the site. Can be used for displaying titles like "You may also like" or "Customers Also Viewed" in customer site.
placeholderNameYou can use the Placeholder Name to explicitly identify where to render the results from corresponding widget. This allows the rendering to be abstracted from widget name. For example, you typically specify the exact website HTML div Id that will be used to render the results on your web site.
algoNameAlgo executed to give results for the widget
slotResultsTop level element which contains the actual recommendation. Each slotResult contains one recommendation (url and all attributes). Each widget can have multiple slotResults depending on the configuration.
For information on elements contained within the slotResults element, see the slotResults table.

Elements within slotResults

Element NameSignificance
slotSlot number the recommendation is associated with
rankRank is the rank of the entity form the catalog that filled the slot. This will help to answer how effective are the recs.

If no filters are applied, then the ranks will be 1, 2, 3 for a widget with 3 slots
If a filter is applied that is not restrictive, the ranks may look like 1, 6, 46
For restrictive filter the ranks may look like 4, 68, 1092343 (first two slots have been filled pretty quickly, while it took 1092343 entities to scan in order to fill out the third one)
scanTimeThe time in milliseconds elapsed in selecting the candidate. This time says how much was spent after the previous candidate was selected.
urlurl of the product recommended
attrsAttributes associated with the product. (Canonical/Catalog name as requested with its values)
ExplanationTop level element that contains the meta data of the recommendation, concisely, the reason a candidate is selected like pin, blacklist etc. For now only 3 items are supported - ItemPin, FilterPin and PairPin. It is mainly for debugging purpose.
ContextSimilar to explanation, says about the context of the recommendation

Elements within Context

Element NameDescription
EntityType of context - Document or product

Elements Within Entity

Element NameDescription
attrsAttributes associated with the product. (Canonical/Catalog name as requested with its values). Similar to attrs for slotresults.


In order to validate recommendation user must check that all results in generated recommendation are strictly following properties defined in RS API request.

Given that the widget is configured to return up to 10 results with a restriction that price is less than 10, the call will produce results that adhere to those criteria.

Proposed Updates

Please see Expanding the rec server’s API.

Megan MayfieldRTI Dev: Recommendation Server API