Skip to main content
RichRelevance

recsForPlacements

Description

This endpoint returns recommendations for a named placement and logs shopper behavior. The recommendations returned by the API respect all merchandising rules set up in the Relevance Cloud dashboard.

URL

Production

Use this URL to request personalization from your production environment.

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

Integration

Use this URL to request personalization 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

 

Parameters

NOTE Only call parameters that you need. RichRelevance operates off a set of APIs that support many applications and clients concurrently. RichRelevance may update and enhance these APIs at any time. If you are building a mobile app, please use our Mobile SDK.

NOTE This endpoint requires that you track click events. See Tracking Events for more details.

 

Name Required or Optional Description
aari Optional

Already added registry items. A single (or list of) product ID(s). If there is more than one product in the registry, separate the IDs using the pipe '|' character.

Example: ​aari=33306|909119|305466

apiClientKey Required

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

apiKey Required

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

atcid Required on Add to Cart page

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

bi Optional

A list of product IDs that should not be recommended in this response. Use the pipe "|" character to separate product IDs.

Example: bi=93874|04495|043945

categoryData Optional

Omits category data (categoryIds and categories) when set to false. The default is true.

Example: categoryData=false

categoryId Required on category_page

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

chi Optional

Supplies category hint IDs. Category hints can be added to any page type. Each category hint qualifies the page for merchandising rules that are associated to the category. Merchants can add multiple category hints to a single page. The values are separated by the pipe "|" character. 

Example: chi=1913000|1903094

count Optional

The total number of products to return in the response. This value overrides the return count set in the placement or in the Search and Browse configuration. For example, if you want to return products 30 through 60, set the value to 30. The maximum value is 1000.

Example: count=30

Note: this is for Search and Browse only.

ctp Optional

Click-through parameter. Used to add parameters to the click-through URL. See Click-through Parameters for more information.

Example: ctp=|0:origin=CJ|1:&campaign=rr

cts Optional

Click-through server. Changes a portion of the click-through URL when a shopper clicks on a recommendation. It specifies the destination server of the click (for example, www.buystuff.com vs. m.buystuff.com). This parameter is typically used during development to keep users within the same environment when clicking on a recommendation. 

Example: cts=http://test.buystuff.com

Note: if the cts parameter is provided in the API request, it overrides the click-through server site configuration setting, and/or cts in the product URL delivered in the feed.

excludeHtml Optional

True/false. If true, it omits the HTML returned in the RichRelevance server response. If false, the response includes the HTML for the placement which is set in the layout of the html field. The default is false. 

Example: excludeHtml=true

excludeItemAttributes Optional

True/false. If true, it removes item attributes from the recommended products data. The default is false.

Example: excludeItemAttributes=true

excludeRecItems Optional

True/false. If true, it completely removes the recommended items structure. This is useful when HTML is sufficient for the response. The default is false.

Example: excludeRecItems=true

fdm Optional

Force Dev Mode. True/false. If true, the parameter will force display. For example, in listen mode, it will return products bypass logging.

Example: fdm=t

filbr Optional

Filter by brand name. The default excludes products of the specified brand from being recommended. See includeBrandFilteredProducts to change the default function. Filter multiple brand names by using the pipe "|" character between names.

Example: filbr=Microsoft|Logitech|Apple

filterAtr Optional

Filter types and values selected by the shopper. Place quotation marks around all attributes, separate the types by using the pipe "|" character, and separate the values by using a semicolon. You must include quotation marks around all attributes.

Example: filterAtr=brand:"adidas"|size:"M";"L"

Note: This is for Search and Browse only, and it needs configuration by RichRelevance first.

flv Optional

Flash version of the browser. It's only used if content displayed is flash.

Example: flv=20.0.0.306

fpb Optional

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

Example: fpb=Microsoft

includeBrandFilteredProducts Optional

True/false. Changes the function of filbr from exclude to include. If not specified, the default is false, which will exclude the specified brand. If true, the brand filter excludes all products except the specified brand.

Example: includeBrandFilteredProducts=true

includeMVTData Optional

True/false. The default is false. If true, it includes details about any multivariate test (MVT) that is running.

Example: includeMVTData=true

Example JSON Response: 

"mvt":
[
{ "testId":12953, "control":false, "treatmentId":15707, "treatmentName":"T2 - recs OFF” }
],
includeSkuData Optional

True/False, the default value is false. If true, any available sku data provided in the SKU Feed will be provided for the returned products.

Example: includeSkuData=true

Example JSON Response:

"skuData": [{
  "color": "White",
  "size": "12",
  "image_url": "http://demandware.edgesuite.net/9400.jpg",
  "sku": "9400"
}, {
  "color": "White",
  "size": "13",
  "image_url": "http://demandware.edgesuite.net/9401.jpg",
  "sku": "9401"
}]

includePriceFilteredProducts

Required for minPriceFilter

and maxPriceFilter parameters

True/false. Changes the function of minPriceFilter and maxPriceFilter from exclude to include. If not specified, the default is false, and it excludes product prices that match the specified range. If true, the filter excludes all products outside of the price range.

Example: includePriceFilteredProducts=true

includeStrategyData Optional

True/false. Default is false. If true, each placement in the response will include the strategy name.

Example: includeStrategyData=true

ipor Optional

Shopper IP address. Only use if the API request is not coming from the shopper’s device (for example, server-side integration).

Example: ipor=255.255.255.255

jcb Required for jsonp

Name of the JavaScript function that JSON data is passed to. Must be specified if jsonp is set to true.

Example: jcb=processData

jsonp Optional

Boolean flag. The only valid value is true. If set to true, the jcb parameter must also be provided.

Example: jsonp=true

maxPriceFilter Optional

The maximum value of the price range filter. This filter matches the sale price of a product, or the list price if no sale price is provided. The value is in cents.

Note: this parameter will not work correctly unless includePriceFilteredProducts is also used. 

Example: maxPriceFilter=10099 (this means $100.99) 

minPriceFilter Optional

The minimum value of the price range filter. This filter matches the sale price of a product, or the list price if no sale price is provided. The value is in cents.

Note: this parameter will not work correctly unless includePriceFilteredProducts is also used. 

Example: minPriceFilter=579 (this means $5.79) 

o

 

Required on purchase_complete_page

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

placements Required

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

pp Required on purchase_complete_page

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 Required on purchase_complete_page

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)

priceRanges Optional

Filter based on the price ranges that products should belong to. This is not applicable for clients with localized product prices. The values are in cents, and the value ranges are separated by the pipe "|" character.

Example: priceRanges=0;100|500;1000

Note: this is for Search and Browse only. 

productId Required on item_page, search_page, purchase_complete_page, and cart_page (when not empty)

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

purchased Required for Search & Browse

Products the shopper purchased in the current session including time tamps (in milliseconds) using UTC time zone for each purchase. The time stamp field must be provided. Separate multiple product IDs using the pipe "|" character.

Example: purchased=pid151800145:1362777947320;1362777947325

q Required on purchase_complete_page

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

returnMinimalRecItemData Optional

True/false. If true, it reduces the information about recommended items to only external ID and click URL. The default is false.

Example: returnMinimalRecItemData=true

rg Optional

Used to identify a particular registry.

Example: rg=Registry123454321

rgt Optional

Registry type ID. Contact RichRelevance for a list of registry type IDs for your site.

Example: ​rgt=wedding

rid Optional

Region ID. Must be consistent with the ID used in the product region feed.

Example: rid=Switzerland-France

searchTerm Required on search_page

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

sessionId Required

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

sgs Optional

Supply user segments. Used for segment-targeted campaigns. List each segment using the format segment_number:segment_name, and then use the pipe "|" character to separate segments. You must pass both the segment ID and a segment name for each segment.

Example: sgs=101:NewUser|202:Male

st Optional

The starting number for the products that you want to return. For example, if you want to return products 30 through 60, set the value to 30.

Note: this is for Search and Browse only. 

Example: st=30

strategySet Optional

A prioritized list of strategy sets that you want returned based on the campaign use case. Please see additional details under Strategy Families listing below. If this is not provided, our recommendation engine will run King of the Hill (KOTH) to provide best recommendations given the information provided.

Example:strategySet=SiteWideBestSellers or strategySet=ProductBoughtBought|ProductViewedViewed

ts Optional

Timestamp. It's used for browser cache busting, and is highly recommended. If excluded, you may see cached responses.

Example: ts=1376676943

udd Optional

Use Dummy Data. True/false. If true, it returns random products for testing.

Example: udd=t

userAttribute Optional

Custom keys and values that describe the current shopper. Separate information using a semicolon and the pipe "|" character.

Example: userAttribute=eye_color:blue;green|hair_color:brown

userId Optional

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

viewed Required for Search & Browse

List the product IDs of the product detail pages viewed by the shopper in the current session. Include time stamps in milliseconds using the UTC time zone for each view. The time stamp field must be provided. Separate multiple product IDs by using the pipe "|" character. If there are multiple views for a product ID, concatenate the time stamps with a semicolon.

Example: viewed=pid1:1409871261000;1409871561000|pid2:1409761261000

rfm Optional

Refinements are used to assure recommended products have a specific attribute value or values. An individual refinement is specified as a colon separated name/value pair.

Example: rfm=name:value

To specify a refinement as the existence of the attribute, you can simply omit the value

Example: rfm=name

To specify multiple refinements, specify them as a delimited list using the pipe character ('|') as the delimiter.

Example: rfm=attributeName|attributeName1:value1|attributeName2:value2

For more information, refer to the Refinements section.

rfb Optional

Refinement Fall-Back. Controls the cul-de-sac fallback behavior of refinements. 

Example: rfb=false

Default value is true, meaning that refinement values that would make reduce recommendations below the placement's minimum threshold will be discarded. 

For more information, refer to the Refinements section.

Example requests

Display the first page (20 products per page) for an anonymous shopper (no user ID) for category 6406:

GET /rrserver/api/rrPlatform/recsForPlacements?apiKey=a6x5029gd6941a22&st=0&count=20&apiClientKey=x3f023fd649003&placements=category_page.richsort&sessionId=27083322340392734752015&userId=&categoryId=6406

Display the first page (20 products per page) for user ID 48454648, and for category 6406:

GET /rrserver/api/rrPlatform/recsForPlacements?apiKey=a6x5029gd6941a22&st=0&count=20&apiClientKey=x3f023fd649003&placements=category_page.richsort&sessionId=27083322340392734752015&userId=48454648&categoryId=6406

Display the next 20 products (products 21-40) for category 6406:

GET /rrserver/api/rrPlatform/recsForPlacements?apiKey=a6x5029gd6941a22&st=20&count=20&apiClientKey=x3f023fd649003&placements=category_page.richsort&sessionId=27083322340392734752015&userId=48454648&categoryId=6406

Display the first page (20 products per page) for user ID 48454648, for category 6406, and only show “color:black” products:

GET /rrserver/api/rrPlatform/recsForPlacements?apiKey=a6x5029gd6941a22&st=20&count=20&apiClientKey=x3f023fd649003&placements=category_page.richsort&sessionId=27083322340392734752015&userId=48454648&categoryId=640&filterAtr=color:black

Example response

The response is a JSON object that lists each product displayed to the shopper. Here’s an example that returns 2 products for the shoes category:

 

{
  "rcs": "eF5j48otK8lM4TGy0DXUNWQpTfZINU80TLG0NNdNtrRM1DUxSk3WNTY3NdI1MjM1MUg1TzI0SzPgKgXqSeYwstBLBAAmHBDP",
  "placements": [
    {
      "htmlElementId": "category_page_0",
      "placementType": "category_page",
      "strategyMessage": "RichSort",
      "html": "",
      "placement": "category_page.richsort",
      "totalItemCount": 15077,
      "recommendedProducts": [
        {
          "clickURL": "http:\/\/recs.richrelevance.com\/rrserver\/apiclick?a=c3c5705fd6524a22&cak=c157ee7e70470913&ct=http%3A%2F%2Fwww.buystuff.com%2F9736903%2Fproduct.html&vg=2daa1dba-bcb7-4afe-1d65-c5540e7a6f9c&stid=165&pti=4&pa=12306&pn=-1&pos=0&p=9736903&channelId=c157ee7e70470913&s=270833223403927347520",
          "regionPriceDescription": "",
          "rating": 4.5700001716614,
          "numReviews": 28,
          "categoryIds": [
            "sub22264",
            "sub2747"
          ],
          "clickTrackingURL": "http:\/\/recs.richrelevance.com\/rrserver\/apiclick?a=c3c5705fd6524a22&cak=c157ee7e70470913&vg=2daa1dba-bcb7-4afe-1d65-c5540e7a6f9c&stid=165&pti=4&pa=12306&pn=-1&pos=0&p=9736903&channelId=c157ee7e70470913&s=270833223403927347520",
          "regionalProductSku": "9736903",
          "imageURL": "na",
          "name": "Women's Lace-Up Rugged Boots",
          "isRecommendable": true,
          "priceCents": 1999,
          "attributes": {
            "size": [
              "9"
            ],
            "material": [
              "Faux Leather"
            ],
            "color": [
              "Brown"
            ],
            "style": [
              "Lace-Up Boots"
            ],
            "shoe width": [
              "Medium"
            ]
          },
          "id": "9736903",
          "categories": [
            {
              "hasChildren": false,
              "name": "Boots",
              "id": "sub2747"
            }
          ],
          "productURL": "http:\/\/www.buystuff.com\/9736903\/product.html",
          "brand": "None"
        },
        {
          "clickURL": "http:\/\/recs.richrelevance.com\/rrserver\/apiclick?a=c3c5705fd6524a22&cak=c157ee7e70470913&ct=http%3A%2F%2Fwww.buystuff.com%2F8342906%2Fproduct.html&vg=2daa1dba-bcb7-4afe-1d65-c5540e7a6f9c&stid=165&pti=4&pa=12306&pn=-1&pos=1&p=8342906&channelId=c157ee7e70470913&s=270833223403927347520",
          "regionPriceDescription": "",
          "rating": 3.7799999713898,
          "numReviews": 60,
          "categoryIds": [
            "sub2747"
          ],
          "clickTrackingURL": "http:\/\/recs.richrelevance.com\/rrserver\/apiclick?a=c3c5705fd6524a22&cak=c157ee7e70470913&vg=2daa1dba-bcb7-4afe-1d65-c5540e7a6f9c&stid=165&pti=4&pa=12306&pn=-1&pos=1&p=8342906&channelId=c157ee7e70470913&s=270833223403927347520",
          "regionalProductSku": "8342906",
          "imageURL": "na",
          "name": "Journee Collection Women's 'Spokane' Regular and Wide-calf Studded Knee-high Riding Boot",
          "isRecommendable": true,
          "priceCents": 4949,
          "attributes": {
            "size": [
              "5",
              "7"
            ],
            "toe shape": [
              "Round"
            ],
            "boot height": [
              "Knee-High Boots"
            ],
            "heel height": [
              "Low Heel"
            ],
            "material": [
              "Faux Leather"
            ],
            "footbed": [
              "Slightly Padded"
            ],
            "color": [
              "Tan"
            ],
            "style": [
              "Riding Boots"
            ],
            "shoe width": [
              "Medium"
            ]
          },
          "id": "8342906",
          "categories": [
            {
              "hasChildren": false,
              "name": "Boots",
              "id": "sub2747"
            }
          ],
          "productURL": "http:\/\/www.buystuff.com\/8342906\/product.html",
          "brand": "Journee Collection"
        }
      ]
    }        
  ],
  "viewGuid": "2daa1dba-bcb7-4afe-1d65-c5540e7a6f9c",
  "status": "ok"
}

Tracking Events

This endpoint will automatically log a page view event when called. It will also automatically log a placement impression for each of the placements returned. For example, if you request three placements but only one is returned, this endpoint will log a placement impression for this returned placement only.

When personalization placements are returned, recsForPlacements will expose both the product URL and click event trackers. When the user clicks on a recommended product, you are required to call a click event tracker for that product before redirecting the user to the product detail page. This is to ensure RichRelevance can track the click along with the views, so that our products can accurately capture CTR data. This API will expose the following URLs:

  • productURL is the direct URL to the Product Detail Page. Use this URL to link to the product page, likely as the href attribute of an <a> tag.
  • clickTrackingURL tracks a product click without redirecting the user to the Product Detail Page. For SEO purposes, you can use this URL together with productURL and trigger a request to clickTrackingURL via a click event listener.
  • clickURL tracks a product click and redirects the user to the Product Detail Page via an HTTP 302 redirect.

To successfully track clicks use one of the following options:

  1. Use clickURL which automatically tracks a product click and redirects the user to the Product Detail Page, or
  2. Use productURL as the final URL, and trigger a request to clickTrackingURL via an event listener. This is the suggested approach when SEO optimization is involved.

Your code should include logic like the following to render personalized product recommendations:


$('#personalization').on('click', 'a', function() {
  var targetURL = $(this).data('clickTrackingURL');
  var img = new Image();
  img.src = targetURL;
});

var recsForPlacementsURL = 'https://recs.richrelevance.com/rrserver/api/rrPlatform/recsForPlacements?apiKey=a6x5029gd6941a22&apiClientKey=x3f023fd649003&placements=home_page.recommend&sessionId=27083322340392734752015'
$.getJSON(recsForPlacementsUrl, function(r) {
  if (!(r.placements && $.isArray(r.placements))) {
    return false;
  }
  
  var placementElement = $('#personalization'); 
  var products = r.placements[0].recommendedProducts;
  for (var i in products) {
    var product = $('<a>')
      .attr('href', products[i].productURL)
      .data('clickTrackingURL', products[i].clickTrackingURL)
      .text(products[i].name)
      .appendTo(placementElement);
  }
}); 

This will create the following HTML structure, and will trigger a click event before redirecting the user to the Product Detail Page.

<!-- The href value is productURL from a recsForPlacements response -->
<div id="personalization">
  <a href="/product/1">Product 1</a>
  <a href="/product/2">Product 2</a>
  <a href="/product/3">Product 3</a>
  <a href="/product/4">Product 4</a>
  <a href="/product/5">Product 5</a>
</div>

Testing

To test integrating on click events, use a web proxy or your browser's Developer Tools to monitor network requests. You should see a request to something that looks like this: 

http://recs.richrelevance.com/rrserver/apiclick?a=5c84741760900058&vg=c12ab4b2...s=1437007681319&pg=1653&p=36714988&ind=0

You should expect this request to have a status code of 200 and empty response body.

IMPORTANT If you do not see this request the page is not logging. Make sure you log clicks in order to send click data to RichRelevance. Failing to log clicks will have a detrimental effect on personalization performances.

 

Refinements

Refinements can be added to apply filters to the recommendations that would be returned. This can be done for an number of reasons such as filtering down the recommendation set to match a promotional landing page or matching the result set as a user navigates using a guided navigation.

If you use more than one refinement, the values are 'AND'ed.  This can mean that while applying refinements (especially multiple refinements) can lead to over-filtering of recommendations, where the returnable recommendations are not sufficient to fill the minimum recommendation count on a placement. By default RichRelevance will remove refinements incrementally until the placement can be fulfilled. This is called a cul-de-sac fallback, and to disable this "fallback" simply add the 'rfb' parameter with a value of 'false'.