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).
Audience
This guide assumes readers:
Benefits
- Server-side integration does not require the Algonomy 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.
Prerequisites
- 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:
- Home Page
- Add To Cart Page
- Cart Page
- Add To Registry Page (coming soon)
- Brand Page
- Category Page
- Error Page
- Generic Page
- Item Page
- Personal Page
- Purchase Complete Page
- Search Page
- Wish List Page (coming soon)
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 | ||
| apiClientKey | ||
| sessionId | ||
| userId |
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 |
Common Optional Parameters
The following parameters are not required but are often useful or should be used as best practice dictates.
| Name | Description | |
|---|---|---|
| rcs |
Algonomy cookie string. This is the encrypted Algonomy 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 Algonomy platform access to a user's Algonomy 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 Algonomy browser cookie, and passes it to and from Algonomy 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.
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 | Algonomy 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. |