Skip to main content
RichRelevance

personalize

Description

recs.richrelevance.com/rrserver/api/personalize

  • Returns content for the given user and placement.

Parameters

Note:  All paramets are case sensitive.

Important: 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 SDKs.

Name Required or Optional Description

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

attribute

Optional

Retrieves custom attributes provided in the catalog feed. Use this parameter multiple times to request more than one attribute by separating each attribute with the ampersand "&" character. Use the asterisk "*" character as the parameter value to request all attributes.

Example: &attribute=COLOR&attribute=SIZE

callback

Optional

Name of the JavaScript function that JSON data will be passed to. It must be specified for JSONP. The value of this parameter is used as the name of the js function in the response.

Example: callback=products_returned

categoryData

Optional

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

Example: categoryData=false

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

cis

Optional

External category IDs used to pass category context information. For the category_page, the expected value is a single external category ID. For other page types, this can be a list of category IDs. The category IDs must be separated by the pipe "|" character. 

Example: cis=2123048|1903094

cn

Optional

Category name.

Example: cn=Baby

cpi

Required for Promo and Email

Email campaign ID. This can be alphanumeric.

Example: cpi=summerCoolOff2016

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.

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 $95.50)

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

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

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

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

pref

Optional

Shopper’s referrer prior to viewing the page. Used for reporting and merchandising. This is highly recommended.

Example: pref=http://www.google.com

recentlyPurchased

Optional

Products the shopper has purchased in the current session. This can be a single product ID or list of product IDs. Products listed here will be considered along with historical data from the RichRelevance system. Use the pipe "|" character to separate the product IDs.

Example: recentlyPurchased=uv2345|xt1234

recentlyViewed

Optional

List product IDs of the product detail pages viewed by the shopper in the current session. Include time stamps in milliseconds using UTC time zone for each view. The timestamp field must be provided. Use the pipe "|" character to separate multiple product IDs and time stamps. If there are multiple views for a product ID, the time stamps can be concatenated using a semicolon.

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

recProductsCount

Optional

Upper limit on the number of recommendations returned by each strategy. The default is 5, and the maximum is 20.

Example: recProductsCount=8

rid

Optional

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

Example: rid=Switzerland-France

sessionId

Optional

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

useCookie

Optional

Use recently viewed product information from the RichRelevance cookie as a basis for recommendations along with manually-given recommendations. Default is yes.

Example: useCookie=yes

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

If no userID is given, recommendations are based on view and purchase history (via the recentlyViewed and recentlyPurchased parameters or cookies) as well as unpersonalized strategies such as CategoryBestSellers. 

Example Request

http://recs.richrelevance.com/rrserver/api/personalize?apiKey=ABCD&apiClientKey=1234&sessionId=sess456&userId=u789&placements=home_page.page_area1

Example Response

{"placements":[
               {"placement":"home_page.full_1",
                "html":"<div><a href="http://recs.richrelevance.com/rrserver/adclick?pcam=350603&pcre=4350&vg=80008603-e4f5-4547-8afa-ba4ff9126046&propt=home_page.full_1&rp=true&a=632d581ca7b9feb3&sgs=&ct=http%3A%2F%2Fi.imgur.com%2FxKE07.jpg"><img src="http://i.imgur.com/xKE07.jpg" alt="Cat"></a><img src="http://i.imgur.com/xKE07.jpg"></div>"
               "creatives":[
                           {"PROMO_ALT_TEXT":"Cat",
                            "PROMO_TRACKER_URL":"http://i.imgur.com/xKE07.jpg",
                            "PROMO_URL":"http://recs.richrelevance.com/rrserver/adclick?pcam=350603&pcre=4350&vg=80008603-e4f5-4547-8afa-ba4ff9126046&propt=home_page.full_1&rp=true&a=632d581ca7b9feb3&sgs=&ct=http%3A%2F%2Fi.imgur.com%2FxKE07.jpg",
                            "PROMO_IMAGE":"http://i.imgur.com/xKE07.jpg",
                            "campaign":"AZ multi layouts test campaign 1",
                           }
                          ]
               }
             ],
status: "OK",
message: "",
"request":{
           "placements":["home_page.full_1"],
           "sessionId":"null",
           "userId":"null",
           "clientKey":"b22b28e5c5a20be7",
           "apiKey":"632d581ca7b9feb3"
          }
 
}

 

Field Description
placements List of placements with promotions based on the request. This is an array of JSON objects, each describing a single placement..
creatives A list of the creatives to be displayed. In most cases, this will only be one.
html Fully formed HTML for the placement based on the layout and selected campaign. It is included in the response by default. Turn off by using the excludeHtml request parameter.
status A list of the creatives to be displayed. In most cases, this will only be one.
errormessage Either ‘ok’ or ‘error’.
request The parameters from the request that RichRelevance used in processing the request. Typically used for testing purposes.
trackingUrl Email open event tracking URL. This should only be used when Promo is rendered within an email.

Example: trackingUrl

http://recs.richrelevance.com/rrserver/emailTracking?a=bc4f2197c160e3dd&amp;s=1&amp;vg=80007fe3-0b35-4b62-5ad3-67513881024f&amp;u=1&amp;cpi=emailCampaign1&amp;pgt=30&amp;pa=rr_promo2&amp;pt=email_page.rr_promo2&amp;cis=292023&amp;cn=the+sale&amp;pcam=580224&amp;pcre=8753