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 Omnichannel Personalization 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. Algonomy operates off a set of APIs that support many applications and clients concurrently. Algonomy may update and enhance these APIs at any time.
NOTE This endpoint requires that you track click events. See Tracking Events for more details.
Note: All parameters are case sensitive.
Name | Required or Optional | Description |
---|---|---|
aari | Optional | |
apiClientKey | Required | |
apiKey | Required | |
atcid | Required on Add to Cart page | |
attributeList | Optional |
This parameter limits the product attribute information included in the result to the specified list of attributes.
Example: If attributeList = gender,color. Then it will return only gender and color attributes in the product attribute information. attributeList=* Returns all product attributes. attributeList= (Empty) Returns all product attributes. Note: If returnMinimalRecItemData option is set to true in the request which naturally returns a minimum set of information, and attributeList option is also specified, the response also includes the attributes specified in the parameter. Minimal rec item data by default does not include the product name or image URL, these elements can be requested by adding "name" or "imageURL", respectively, to the attributeList. |
bi | Optional | |
categoryData | Optional | |
categoryId | Required on category_page | |
chi | Optional | |
count | Optional | |
ctp | Optional | |
cts | Optional | |
cv | Optional |
Cart value. Used for targeted campaigns involving cart value. It's expressed in cents; for example, $10 is represented as 1000. Example: cv=9550 (this would equal to $95.50) |
excludeHtml | Optional | |
excludeItemAttributes | Optional | |
excludeRecItems | Optional | |
fdm | Optional |
Force Display Mode. True/false. If true, the parameter will force display. For example, in listen mode, it will return products bypass logging. Valid Values:
|
filbr | Optional | |
filcat | Optional |
Specify the category to filter.
|
filcatinc | Optional |
Filter along category (requires specification of category with 'filcat')
|
filterAtr | Optional | |
flv | Optional | |
fpb | Optional | |
includeBrandFilteredProducts | Optional | |
includeMVTData | Optional | |
includeMVTDetailedData | Optional |
True/false. The default is false. If true, it includes details about any multivariate test (MVT) that is running. The “eligible” string parameter will define that if the user is eligible for an MVT test or not. Example: includeMVTDetailedData=true Example JSON Response:
When set to true, for Placement Type of Tests, the response will include a new section "mvtTreatments” providing MVT details that a placement is associated with. Example JSON Response:
Note:
|
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 |
|
includeStrategyData | Optional | |
ipor | Optional | |
jcb | Required for jsonp | |
jsonp | Optional | |
maxPriceFilter | Optional | |
minPriceFilter | Optional | |
o
|
Required on purchase_complete_page | |
pageCount | Optional |
The total number of pages to return in the response. The total number of products returned are (count * pageCount), up to the total number of products in the category. Default pageCount is 1. This feature allows paginated Discover responses to be incorporated into faceted search and navigation systems. For large pageCount values, we advise returning small amounts of data per product, such as with these additional parameters : "&excludeHtml=true&excludeItemAttributes=true&returnMinimalRecItemData=true" Example: pageCount=50 Note: this is for Discover only. |
placements | Required | |
pp | Required on purchase_complete_page | |
ppc | Required on purchase_complete_page | |
priceRanges | Optional | |
productId | Required on item_page, add_to_cart_page, purchase_complete_page, and cart_page (when not empty) | |
purchased | Required for Find & Discover | |
q | Required on purchase_complete_page | |
rcs | Required | First party cookie string. This is a encrypted value of RichRelevance cookies. It should be passed as it was received in the earlier API response. |
returnMinimalRecItemData | Optional |
This will limit the recommendedProducts json to 4 attributes: id, productURL, clickURL, clickTrackingURL |
rg | Optional | |
rgt | Optional | |
rid | Optional | |
searchTerm | Required on search_page | |
sessionId | Required | |
sgs | Optional | |
st | Optional | |
strategySet | Optional | |
ts | Optional | |
udd | Optional | |
userAttribute | Optional | |
userAttributeReplace | Optional |
Usage is same as userAttribute, except that the attributes sent along with userAttributeReplace will replace all previously sent values for that attribute. Example: userAttribute=eye_color:|hair_color: |
userId | Optional | |
viewed | Required for Find & Discover | |
rfm | Optional |
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 reduce recommendations below the placement's minimum threshold will be discarded. For more information, refer to the Refinements section. |
mvt_ftr |
Optional | Stands for 'MVT Force Treatment'. entering a treatment id will force the response to be from the specified treatment. |
Example requests (Recommend)
Retrieve the Home Page placement with placement ID rr1 for user with ID 48454648:
GET /rrserver/api/rrPlatform/recsForPlacements?apiKey=showcaseparent&apiClientKey=776cdd80331919e7&userId=48454648&sessionId=827ccb0eea8a706c4c34a16891f84e7b&placements=home_page.rr1
Request the Item Page placement with the placement ID vertical_rail, using the seed product ID 24516217 for the user with ID 48454648.
GET /rrserver/api/rrPlatform/recsForPlacements?apiKey=showcaseparent&apiClientKey=776cdd80331919e7&userId=48454648&sessionId=827ccb0eea8a706c4c34a16891f84e7b&placements=item_page.vertical_rail&productId=24516217
Request an the Add to Cart Page placement with the ID demo_mobile, for the user with ID 48454648, passing 24516217 (the ID of the product added to the cart) in the atcid parameter.
GET /rrserver/api/rrPlatform/recsForPlacements?apiKey=showcaseparent&apiClientKey=776cdd80331919e7&userId=48454648&sessionId=827ccb0eea8a706c4c34a16891f84e7b&placements=add_to_cart_page.demo_mobile&atcid=24516217
IMPORTANT: If you are doing a server side implementation, make sure to add compression headers to you request. This will allow RR servers to compress the response, which will result in a smaller payload and a faster response time. Example:
Accept-Encoding: deflate, gzip
Example response (Recommend)
{ "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" }
Example requests (Discover)
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 (Discover)
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 thehref
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 withproductURL
and trigger a request toclickTrackingURL
via a click event listener.clickURL
tracks a product click and redirects the user to the Product Detail Page via an HTTP 301 redirect.- amrid tracks the click to the Advanced Merchandising rule that returned the product recommendation.
To successfully track clicks use one of the following options:
- Use
clickURL
which automatically tracks a product click and redirects the user to the Product Detail Page, or - Use
productURL
as the final URL, and trigger a request toclickTrackingURL
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.
In order to force Development mode, use 'dev=true'.
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'.