Skip to main content
RichRelevance

Integration: API (Recommend)

Overview

This documentation describes how to use the Recommend APIs for server-side integration. Our APIs are REST-like and return JSON for all responses. They also support cross-origin resource sharing, allowing you to interact securely with them via client-side web applications (although, you should not expose your secret API keys in any public website's client-side code).

Intended Audience

This guide assumes readers:

  • Are experienced web or application developers
  • Are familiar with REST APIs
  • Understand how to deserialize and use JSON data
  • Have a working knowledge of ecommerce web sites and applications
  • Are already familiar with Recommend

What are the benefits of this feature?

  • Server-side integration does not require the RichRelevance p13n.js (short for personalization) media library to be loaded and called on every web page of your site.
  • The API can be used for applications that are not web-based, such as stand-alone call center and POS applications.
  • Responses can be handled with server-side code written in programming languages that are not restricted to running in a web browser. This can be a good option when additional resources or back-end systems are necessary to handle responses or format product recommendations. For example, if the prices of your products change more frequently than is feasible to communicate to the Relevance Cloud, you could use server-side code to use the product IDs returned in the recsForPlacements API response to lookup real-time prices in your product management system or product database, and then display those current prices on your web site.

What are the drawbacks of this feature?

  • It's more difficult for RR integration consultants to assist with debugging, because of the lack of visibility into the response handling code on the server-side.
  • You have less control of the format of the response. When requesting recommendations through the recsForPlacements API, most of the data associated with a recommended product is returned, including all of its categories and attributes. The size of the response can be paired down using parameters passed in the request, but the exact format and layout of the JSON response cannot be customized in the same way that it can be when using client-side integration.

How It Works

Provide some background information, what's happening behind the scenes, etc

Recommend APIs

The main API for requesting recommendations from Recommend is the recsForPlacements API, and the rest of this document focuses on how to use it.

The first step in integrating a page on your site is deciding which page type most closely matches the type of web page (or part of your application) you wish to make a request for. Page type plays a significant role in the personalization process, as it sets the context that the Experience Optimizer uses to determine in real-time which recommendation strategies have the highest probability of influencing a customer to make a purchase. There are required parameters for each page type. Below are several example recsForPlacement API calls that illustrate server-side integration with the following common ecommerce web page types:  

Please see the recsForPlacements reference page for a comprehensive list of input parameters.

Related APIs

There are several other related APIs that can be used instead of or in conjunction with the recsForPlacements API to update and query the Recommend system, including APIs for updating your product catalog, and querying Recommend for information associated with your users. These are mostly beyond the scope of this document. A list of the other APIs is available on the Relevance Cloud: APIs reference page.

API Endpoints

Production

Use this URL to request recommendations for your production environment:

https://recs.richrelevance.com/rrserver/api/rrPlatform/recsForPlacements

Integration

Use this URL to request recommendations from your QA, staging or development environment. This way, you can test changes (such as merchandising or strategy rules) without impacting your production environment.

https://integration.richrelevance.com/rrserver/api/rrPlatform/recsForPlacements

Authentication

Authenticate your request by including your API key and API client key in your API requests. You can manage your API keys in the Dashboard. Your API keys carry many privileges, so please keep them secure. Do not share your secret API keys in publicly accessible areas such as GitHub, searchable pastebin sites, or client-side code. 

JSON-P Callbacks

To have the response of a recsForPlacements API call wrapped in a JSON function, you can turn  on JSON-P with the jsonp flag and provide a JavaScript callback function in the jcp parameter. E.g.: ?jsonp=true&jcp=myCallback

JSON-P is typically used to get around cross domain issues. For example, it can be useful when using recommendations returned via the API in an application that runs within a web browser. However, we recommend using our Core JSON Integration instead of the recsForPlacements API for web-based applications.

Client Errors

Most error conditions, including those caused by passing in invalid parameter values, will return an HTTP status of 200 OK with a response body describing the error. Thus it is usually necessary to parse the response in order to determine more details about the error.

{
  "errormessage": "An internal error occurred while processing the recsForPlacements API request",
  "status": "error"
}

If there are internal errors processing the request (rare) you may receive an HTTP 500 (5xx) response.

Parameters

The following is a walk-through of which parameters to include when making recsForPlacements API requests, broken out by page type. For an exhaustive list of all the parameters that can be passed into the API please see the recsForPlacements reference.

Common Required Parameters

The following parameters are required by recsForPlacements API regardless of page type.

Name   Description
apiKey  

A unique key that identifies the site. Each RichRelevance client has a unique API key to separate data and traffic from other clients. This is provided by RichRelevance.

Example: apiKey=4faeaf752ee40a0f

apiClientKey  

A unique key specific to each API implementation. It identifies the specific application or client for reporting, permissions, and merchandising. This is provided by RichRelevance.

Example: apiClientKey=b0126f995ac848159d

sessionId  

Identifies a single visit by a shopper.  Sessions are used by behavioral models (to scope user behaviour in a shopping session) and reporting metrics.

Example: sessionId=93484

userId  

User ID. A unique string to identify each shopper (user). All shopper behavior is stored using this key. It is case-sensitive, and should be the same user ID sent to RichRelevance in other applications.

Example: userId=0982347

Note: if the user is in an non-logged in state, please leave the value of the userId parameter empty. Recommend will use the value of sessionId as a provisional user ID, and link any anonymous behavioral data collected to the user's actual user ID once the user has logged in.

placements  

List of placement identifiers. Each identifier consists of a page type and a placement name. The identifiers are separated by the pipe "|" character.

  • You'll receive one set of recommendations per placement.
  • All placements must be for the same page type.
  • The first placement is assumed to be the "best" placement, and will receive the best recommendation strategy.
  • When multiple placements are requested, each will receive a unique strategy and unique products.

Example: placements=item_page.horizontal|item_page.vertical

Common Optional Parameters

The following parameters are not required but are often useful or should be used as best practice dictates.

Name   Description
rcs  

RichRelevance cookie string. This is the encrypted RichRelevance cookie for the user associate with the API request. It should be passed as it was received in an earlier API response.

Note: the rcs parameter allows merchants to effectively give the RichRelevance platform access to a user's RichRelevance browser cookie by acting as a cookie proxy (or cookie pass-through). This is a process in which the merchant reads and writes a user's RichRelevance browser cookie, and passes it to and from RichRelevance via the server-side API.

chi  

Category Hint ID. This parameter can be passed for any page type to explicitly set the category context (category ID), or override the category that would normally be used for the page. This can be useful on pages in which the category is ambiguous, such as item pages of items that belong to multiple categories.

For pages other than category pages, if you do not explicitly set the category context, some strategies will derive category information from the product ID. Instead, it may be desirable to set the context explicitly. For example, to match the state of the user’s bread crumb trail. (This parameter is often used with Item and Add To Cart page types.)

Category hints can be added to any page type. More than one category hint can be added separated by a pipe character ("|"). Each category hint qualifies the page for merchandising rules that are associated with the category.

Example: chi=casual_tops|womens_activewear|activewear

productId  

Up to 15 product IDs can be passed in the productId parameter on the Search and Category page types, each separated by a pipe character ("|"). It is considered best practice to pass product IDs on Search and Category pages to provide better context for strategies.

Example: productId=A040520003423|J040520076542|L0405200903939|J040520089878

Page Type Specific Parameters

In addition to the common parameters above, the following table describes the additional parameters required by each page type.

Page Type Page Type Specific Parameters Example API Call
Home Page    
Add To Cart Page
atcid

Add to Cart ID. This can be a single product ID or a list of product IDs. If more than one product is added to the cart, separate the product IDs by using the pipe "|" character.

Example: atcid=uv2345|xt1234

 

GET /rrserver/api/rrPlatform/recsForPlacements?apiKey=d4ff21d55a1368fc&apiClientKey=42f5962fe3ed493e&userId=12345&sessionId=827ccb0eea8a706c4c34a16891f84e7b&placements=add_to_cart_page.atc_page_rr1_test&atcid=CON-NC4P-15454W2K%7CD1H79AV
Cart Page
productId

A single product ID, or a list of product IDs. Part of an order definition on the purchase complete page. Use the pipe "|" character to separate the product IDs.

Example: productId=uv2345|xt1234

GET /rrserver/api/rrPlatform/recsForPlacements?apiKey=d4ff21d55a1368fc&apiClientKey=42f5962fe3ed493e&userId=12345&sessionId=827ccb0eea8a706c4c34a16891f84e7b&placements=cart_page.rr_warranties&productId=WHYM-F-CP23-N
Brand Page
fpb

The brand featured on the page. Used to set the seed for brand-seeded strategies, such as Brand Top Sellers.

Example: fpb=Microsoft

GET /rrserver/api/rrPlatform/recsForPlacements?apiKey=d4ff21d55a1368fc&apiClientKey=42f5962fe3ed493e&userId=12345&sessionId=827ccb0eea8a706c4c34a16891f84e7b&placements=brand_page.rr1_test&fpb=Lenovo
Category Page
categoryId

The category ID of the category the merchant wants to investigate. The value must match the external ID provided by the merchant to RichRelevance for the category.

Example: categoryId=902312

GET /rrserver/api/rrPlatform/recsForPlacements?apiKey=d4ff21d55a1368fc&apiClientKey=42f5962fe3ed493e&userId=12345&sessionId=827ccb0eea8a706c4c34a16891f84e7b&placements=category_page.rr1%7Ccategory_page.rr2&categoryId=C-JF
Error Page  
GET /rrserver/api/rrPlatform/recsForPlacements?apiKey=d4ff21d55a1368fc&apiClientKey=42f5962fe3ed493e&userId=12345&sessionId=827ccb0eea8a706c4c34a16891f84e7b&placements=error_page.rr1
Generic Page  
GET /rrserver/api/rrPlatform/recsForPlacements?apiKey=d4ff21d55a1368fc&apiClientKey=42f5962fe3ed493e&userId=12345&sessionId=827ccb0eea8a706c4c34a16891f84e7b&placements=generic_page.rr1_test
Item Page
productId

A single product ID, or a list of product IDs. Part of an order definition on the purchase complete page. Use the pipe "|" character to separate the product IDs.

Example: productId=uv2345|xt1234

GET /rrserver/api/rrPlatform/recsForPlacements?apiKey=d4ff21d55a1368fc&apiClientKey=42f5962fe3ed493e&userId=12345&sessionId=827ccb0eea8a706c4c34a16891f84e7b&placements=item_page.rr_recommended_qa&productId=E7W53A%230D1&chi=C-CC
Personal Page

 

GET /rrserver/api/rrPlatform/recsForPlacements?apiKey=d4ff21d55a1368fc&apiClientKey=42f5962fe3ed493e&userId=12345&sessionId=827ccb0eea8a706c4c34a16891f84e7b&placements=personal_page.rr1
Purchase Complete Page
productId

A single product ID, or a list of product IDs. Part of an order definition on the purchase complete page. Use the pipe "|" character to separate the product IDs.

Example: productId=uv2345|xt1234

o

Order ID. Part of the order definition. Example: o=902312

pp

Product prices. A list defining the prices of purchased products. The index of product prices in the list corresponds to the products passed in productId. This is part of the order definition. Use either pp or ppc to define the price of items purchased. If you use pp, the site’s currency multiplier is applied. The values are separated by the pipe "|" character.

Example: pp=29.99|32.97

ppc

Product prices in cents. A list defining the prices of purchased products. The index of product prices in the list corresponds to the products passed in productId. This is part of the order definition. Use either pp or ppc to define the price of items purchased. If you use ppc, the site’s currency multiplier is not applied.

The passed value is accepted as-is, and is converted from a string to an integer. Be certain that the string you pass contains only numerals (no currency symbols or separators). The values are separated by the pipe "|" character.

Example: ppc=2999|3297 (these values are $29.99 and $32.97)

q

Item quantities. A list defining the quantities of products purchased. The index of quantities in the list corresponds to the index of the products passed in productId. This is part of the order definition. Multiple entries are separated by the pipe "|" character.

Example: q=2|1

 

GET /rrserver/api/rrPlatform/recsForPlacements?apiKey=d4ff21d55a1368fc&apiClientKey=42f5962fe3ed493e&userId=12345&sessionId=827ccb0eea8a706c4c34a16891f84e7b&placements=purchase_complete_page.rr1&productId=4XB0G88733&o=300242352342&q=1&pp=228.99&ppc=22899
Search Page
searchTerm

The search term typed in by the shopper. You can also use the productId parameter to provide product IDs of the products in the search results.

Example: searchTerm=adriana lima

GET /rrserver/api/rrPlatform/recsForPlacements?apiKey=d4ff21d55a1368fc&apiClientKey=42f5962fe3ed493e&userId=12345&sessionId=827ccb0eea8a706c4c34a16891f84e7b&placements=search_page.rr1%7Csearch_page.rr2&searchTerm=Lenovo

Example Response

The response is a JSON object containing a list of recommended product objects for the current user. Here’s an example response with two recommended products from the shoes category:

Response Header

HTTP/1.1 200 OK
Date: Thu, 21 Jun 2018 22:16:47 GMT
Set-Cookie: m=1;Path=/
Expires: Thu, 01 Jan 1970 00:00:00 GMT
Content-Type: application/json;charset=utf-8
Vary: Accept-Encoding
Content-Length: 2390
Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET, OPTIONS, POST
Access-Control-Allow-Credentials: true
Access-Control-Allow-Headers: Content-Type, Access-Control-Request-Method, Access-Control-Request-Headers, Authorization, X-Requested-With

Response Body

{
  "rcs": "eF5j4cotK8lM4TMzsNA11DVkKU32MEkyBAJjM11jYzMzXRNTozRdA0sgYZxiammQaGJmZmaaDABuTQ0O",
  "placements": [
    {
      "htmlElementId": "home_page_0",
      "placementType": "home_page",
      "strategyMessage": "Shop Top Sellers",
      "html": "",
      "placement": "home_page.rr1",
      "recommendedProducts": [
        {
          "clickURL": "https://integration.richrelevance.com/rrserver/apiclick?a=showcaseparent&cak=776cdd80331919e7&ct=http%3A%2F%2Flabs.richrelevance.com%2Fstorre%2Fcatalog%2Fproduct%2Fview%2Fsku%2F22127002&vg=4b121136-3366-452f-092f-3d590a46665c&stid=126&pti=9&pa=11339&pos=0&p=22127002&channelId=776cdd80331919e7&s=827ccb0eea8a706c4c34a16891f84e7b&u=12345&mvtId=-1&mvtTs=1529712166361",
          "regionPriceDescription": "",
          "salePriceRangeCents": [
            1,
            1
          ],
          "rating": 3.884,
          "numReviews": 0,
          "priceRangeCents": [
            1,
            1
          ],
          "categoryIds": [
            "Electronics",
            "Electronics.Computers",
            "Electronics.Computers.Tablet PCs"
          ],
          "clickTrackingURL": "https://integration.richrelevance.com/rrserver/apiclick?a=showcaseparent&cak=776cdd80331919e7&vg=4b121136-3366-452f-092f-3d590a46665c&stid=126&pti=9&pa=11339&pos=0&p=22127002&channelId=776cdd80331919e7&s=827ccb0eea8a706c4c34a16891f84e7b&u=12345&mvtId=-1&mvtTs=1529712166361",
          "salePriceCents": 1,
          "regionalProductSku": "22127002",
          "imageURL": "http://labs.richrelevance.com/storre/media/catalog/product/n/e/nextbook-7quot-tablet-with-8gb-memory-with-google-mobile-services-73fbdb1640b18e99695aa87c7da712f5.jpg",
          "name": "\"Nextbook 7\\\" Tablet with 8GB Memory with Google Mobile Services\"",
          "genre": "default",
          "isRecommendable": true,
          "priceCents": 6900,
          "attributes": {
            "MktplcInd": [
              "W"
            ],
            "Clearance": [
              "N"
            ],
            "97CentShipping": [
              "N"
            ],
            "Rollback": [
              "N"
            ],
            "Online": [
              "Y"
            ],
            "ListPrice": [
              "79"
            ],
            "AddToCart": [
              "Y"
            ],
            "IsReducedPrice": [
              "N"
            ],
            "IsSubmap": [
              "N"
            ],
            "S2S": [
              "Y"
            ]
          },
          "id": "22127002",
          "categories": [
            {
              "hasChildren": false,
              "name": "Electronics",
              "childCategories": [],
              "ancestorCategories": [],
              "id": "Electronics",
              "isActive": false
            },
            {
              "hasChildren": false,
              "name": "Computers",
              "childCategories": [],
              "ancestorCategories": [],
              "id": "Electronics.Computers",
              "isActive": false
            },
            {
              "hasChildren": false,
              "name": "Tablet PCs",
              "childCategories": [],
              "ancestorCategories": [],
              "id": "Electronics.Computers.Tablet PCs",
              "isActive": false
            }
          ],
          "productURL": "http://labs.richrelevance.com/storre/catalog/product/view/sku/22127002",
          "brand": "Nextbook"
        }
      ]
    }
  ],
  "viewGuid": "4b121136-3366-452f-092f-3d590a46665c",
  "status": "ok"
}

Resources

Below are detailed descriptions of the resources (JSON objects) returned by successful calls to the recsForPlacements API.

Response Object

The response object contains Placement Objects corresponding to each placement requested in the recsForPlacements API call.

Field Description
viewGuid A unique identifier for this set of recommendations.
rcs RichRelevance cookie for the merchant to pass to and from the user's browser (cookie proxy / pass-through).
placements An array of JSON placement objects. Each placement contains a list of recommended products.
status Either "ok" or "error".
errormessage If the status is "error" this contains a description of the error.

Placement Object

Placement Objects contain one or more recommended Products determined by the strategies that apply to the placement.

Field Description
htmlElementId ?
placementType The page type of the placement.
strategyMessage The strategy message for the strategy that determined the recommended products for the placement.
html ?
placement The ID of the placement.
recommendedProducts A JSON array of recommended products for the placement.

Product Object

Product Objects represent individual Products that are recommended for a given placement.

Field Description
id The ID of the product.
name The name of the product.
imageURL The URL for the image of the product.
clickURL The click URL. This URL will both track a customer's click on a recommendation and redirect the user to the Product Detail Page.
productURL A link to a page featuring the product.
clickTrackingURL A link to track a product click without redirecting the user to the Product Detail Page. Can be used in conjunction with product URL as an alternative to using clickURL.
rating A decimal value, representing the overall rating of a product. The default is -1.0 (no rating).
numReviews An integer value representing the number of reviews available for a product. Defaults to 0.
priceRangeCents An array representing the minimum and maximum prices of the product in cents.
priceCents The price of the product in cents.
salePriceCents An array representing the minimum and maximum sale prices of the product in cents.
regionalProductSku A SKU for the product, corresponding to the user's region. [How does this relate to Region and SKU feeds?]
regionalPriceDescription ?
attributes A JSON array of product attribute objects.
brand The brand of the product.
genre The genre of the product.
categoryIds An array of category IDs the product belongs to.
categories An array of category objects representing the categories the product belongs to.
isRecommendable Whether the product is recommendable (always true).

Attribute Object

A Product object may contain one or more Attribute Objects. These are the attributes that are passed to Recommend via the Product Catalog Feed and/or the Catalog Update API.

Field Description
Attribute Name* The name of the attribute.
Attribute Value* The value of the attribute.

* These are defined in Product Attribute Feed File and/or The Catalog Update API.

Category Object

A Product object may contain one or more Category Objects. Categories are defined in the Product Catalog Feed and/or the Catalog Update API.

Field Description
id The ID of the category.
name The name of the category.
childCategories An array of child categories (if this is a parent category).
ancestorCategories An array of ancestor categories (if this is a child category). [How many generations?]
isActive Whether the category is active.

 

  • Was this article helpful?