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 through client-side web applications. (although, you should not expose your secret API keys in any public website's client-side code).

This guide assumes the 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.

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 Omnichannel Personalization, 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 Algonomy 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 while using client-side integration.

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

• Brand Page

• Category Page

• Error Page

• Generic Page

• Item Page

• Personal Page

• Purchase Complete Page

• Search Page

• Wish List Page (coming soon)

Refer to recsForPlacements reference page for a comprehensive list of input parameters.

Related APIs

There are a number of other APIs related to the topic at hand that may be of interest 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 Personalization Cloud: APIs reference page.

API Endpoints for Server-Side Implementations

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

IMPORTANT: Once you make the change, please coordinate with your Algonomy consultant to update the vanity URL to https://[customername].algorecs.com or https://recs.algorecs.com. All the rest of the parameters used in the API call and the instrumentation mechanism can remain the same.

API Endpoints for Client-Side Implementations

We do not recommend making direct API requests from web browsers to the Personalization Cloud. Kindly route the API requests through your own domain using the reverse proxy method based on the API gateway. For more details on API gateway Reverse Proxy method, refer to API Reverse Proxy Domain.

Please refer to the client-side integration guide for more details on our JavaScript solution. In case you have instrumented direct API calls from your web browsers to the Personalization Cloud, we recommend updating the domain to our exclusive new data capture domain called https://recs.algorecs.com in your API endpoints for better security.

Production

Use this URL to request recommendations for your production environment:

https://recs.algorecs.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.algorecs.com/rrserver/api/rrPlatform/recsForPlacements

IMPORTANT: Once you make the change, please coordinate with your Algonomy consultant to update the vanity URL to https://[customername].algorecs.com or https://recs.algorecs.com

All the rest of the parameters used in the API call and the instrumentation mechanism can remain the same.

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.

Common Optional Parameters 

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

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.

Placement Object

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

Product Object

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

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.

* These are defined in Product Catalog Feed 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.