Skip to main content
RichRelevance

find/search

Description

GET http://service.richrelevance.com/find/v1/<API_KEY>

Returns product results for a search term.  This is the main API to initiate search requests.  You can specify multiple parameters such as number of products to return, page number, filters to apply, etc to refine the search request further.

The response is a list of product information and facets needed to render a search results page. It could change based on search attributes settings available on FIND dashboard. (See below for more details on the response object)

Parameters

 

Name Data Type Required or Optional Description

query

String Required

The text to search.  

Example: query=shoes

lang

String Required

The language of the search.  Examples: "en", "fr", "jp".

start

Integer Required

The starting position of the results you want for the specified query.  It's a zero indexed system.  

For example if you want the first 20 results, you will set start=0, if you want the next 20 results (21-40), you will set start=20.

rows

Integer Required Rows describe how many results to return back.  If you want to show 20 products on the page, set rows=20.

placement

String 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

sessionId

String 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

userId String 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. 

filter

String Optional

Apply a filter to the search term.   You can apply multiple filters.  For a list of all applicable fields see section below called "Fields".  The response (see section called "Response" below) also provides you a list of facets and how to filter by the facets.

Here's an example of how you filter for the brands "adidas" and "puma"

filter=product_brand:\"adidas\"&filter=product_brand:\"puma\"

facet

String Optional

Specify which fields/attributes you want facets for in the response.  If you don't specify any, then all attributes configured to be facetable (in the dashboard) will be returned in the response.

For a list of all applicable fields see section below called "Fields".

sort

String Optional

Specify how you want to sort the products.  The default is a personalized sort.  You can instead sort by any product attribute that you specified in your catalog.  For a list of all applicable fields see section below called "Fields".

We recommend that in addition to the personalized relevant sort (the default) you give options for shoppers to sort by these fields

  • product_rating (Average rating from reviews)
  • product_saleprice_cents (Sale price)
  • product_pricecents (Regular price)
  • product_release_date (The newness of the product)

Also, specify whether you want the sort to be in Ascending or Descending order.  Allowed values are: "ASC" or "DESC"

callback

String 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

channelId

String Optional

A channel is a description of the caller of this API.  It's mostly used to describe whether this API is being used in an Android app or a Call center app.

Example: ​channel=CallCenter

log

Boolean Optional

If set to true this will log the search request event.  The default behavior is for this to be false.  In that case searchTrackingUrl should be used to provide search tracking.

region

String Optional Region Identifier
pref String Optional

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

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

rcs String Optional 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.
ssl Boolean Optional If set to true than clickUrl and searchTrackingUrl are returned with https protocol.

Example Request

http://service.richrelevance.com/find/v1/<API_KEY>?query=shoes&lang=en&sessionId=sess456&userId=u789&placement=search_page.search1

Example Response

{
   "request":{
      "apiKey":"showcaseparent",
      "placements":[
         "search_page.sort"
      ],
      "sessionId":"s1234",
      "userId":"u1234"
   },
   "placements":[
      {
         "searchTrackingUrl":"http://localhost:8101/rrserver/api/v1/service/track/search/showcaseparent?query=t&lang=en&user=u1234&session=s1234&channel=WEB&region=&numFound=1956&placement=search_page.sort&page=0&rcs=eF4FwbENgDAMBMCGill4yUls570BcyRgiYIOmJ-7Zb2_5zo2F6KosfReW3gEWCHLO3eK2NAUpOYJ1WmYVEeatWAdPpg_V-4RTg",
         "rcs":"eF4FwbENgDAMBMCGill4yUls570BcyRgiYIOmJ-7Zb2_5zo2F6KosfReW3gEWCHLO3eK2NAUpOYJ1WmYVEeatWAdPpg_V-4RTg",
         "links": {
            "directlink": [
               {
                  "id": "direct-link-id",
                  "title": "direct-link-title",
                   "subtitle": "direct-link-subtitle",
                  "url": "direct-link-url"
               }
            ],
            "banner": [
               {
                  "id": "banner-id",
                  "title": "banner-title",
                  "subtitle": "banner-subtitle",
                  "url": "banner-url",
                  "image_url": "image-ur"
               }
            ],
            "sponsored": [
               {
                  "id": "sponsored-id",
                  "title": "sponsored-title",
                  "subtitle": "sponsored-subtitle",
                  "url": "sponsored-url",
                  "image_url": "sponsored-image-url"
               }
            ]
         },
         "docs":[
            {
               "clickUrl":"http://localhost:8101/rrserver/api/v1/service/track/click/showcaseparent?a=showcaseparent&vg=80015896-f4fe-44c5-41ab-6654e0877e89&pti=2&pa=sort&hpi=0&stn=PersonalizedProductSearchAndBrowse&stid=184&rti=2&sgs=&u=u1234&mvtId=0&mvtTs=1458177239699&uguid=8005b4f0-f4fe-44c5-c846-f553982b6b8f&channelId=WEB&s=s1234&pg=-1&page=0&query=t&lang=en&p=10308694&ind=0&ct=http://labs.richrelevance.com/storre/catalog/product/view/sku/10308694",
               "imageId":"http://labs.richrelevance.com/storre/media/catalog/product/t/-/t-gel-original-shampoo-8.5oz-1e2df9930cf89d1614debdbaa3feaf38.jpg",
               "linkId":"",
               "salePriceCents":798,
               "name":"T-Gel Original Shampoo, 8.5oz",
               "priceCents":798,
               "id":"10308694"
            },
            {
               "clickUrl":"http://localhost:8101/rrserver/api/v1/service/track/click/showcaseparent?a=showcaseparent&vg=80015896-f4fe-44c5-41ab-6654e0877e89&pti=2&pa=sort&hpi=0&stn=PersonalizedProductSearchAndBrowse&stid=184&rti=2&sgs=&u=u1234&mvtId=0&mvtTs=1458177239699&uguid=8005b4f0-f4fe-44c5-c846-f553982b6b8f&channelId=WEB&s=s1234&pg=-1&page=0&query=t&lang=en&p=10339306&ind=1&ct=http://labs.richrelevance.com/storre/catalog/product/view/sku/10339306",
               "imageId":"http://labs.richrelevance.com/storre/media/catalog/product/a/t/atampampt-2000-minutes-rechargeable-us-ampamp-international-prepaid-phone-card-c9152dba32526ce359e426e5bcad0903.jpg",
               "linkId":"",
               "salePriceCents":4488,
               "name":"AT&amp;T 2000-Minutes Rechargeable US &amp; International PrePaid Phone Card",
               "priceCents":6320,
               "id":"10339306"
            }
         ],
         "numFound":1956,
         "placement":"search_page.sort",
         "spellchecked":null,
         "addtoCartParams": "page=1&query=t&lang=en&searchConfigId=123434sdef3222",
         "facets":[
            {
               "values":[
                  {
                     "filter":"{!tag=categories_facet}categoryIds:\"871098905\"",
                     "count":842,
                     "value":"Apparel"
                  },
                  {
                     "filter":"{!tag=categories_facet}categoryIds:\"1985805468\"",
                     "count":519,
                     "value":"Beauty"
                  }
               ],
               "facet":"categories_facet"
            },
            {
               "values":[
                  {
                     "filter":"{!tag=brand_facet}brand_facet:\"Generic\"",
                     "count":126,
                     "value":"Generic"
                  },
                  {
                     "filter":"{!tag=brand_facet}brand_facet:\"Hanes\"",
                     "count":77,
                     "value":"Hanes"
                  }
               ],
               "facet":"brand_facet"
            },
            {
               "min":0,
               "max":10000,
               "values":[
                  {
                     "filter":"product_effectiveprice_cents:[0 TO 5000]",
                     "count":126,
                     "value":"0:5000"
                  },
                  {
                     "filter":"product_effectiveprice_cents:[5000 TO *]",
                     "count":77,
                     "value":"5000:*"
                  }
               ],
               "facet":"product_effectiveprice_cents"
            },
         ]
      }
   ],
   "message":"",
   "status":"OK"
}
Name Description
request The parameters from the request that RichRelevance used in processing the request. Typically used for testing purposes.
placements

In almost all cases there should only be 1 placement requested for search.  This object will contain all the information needed to render the search results on a page/app.

This is a nested field that contains multiple fields:

  1. searchTrackingUrl:  A URL used for logging.  This is used in cases when the application doesn't ask to log requests when making the call to search but would like to log at a later time.  Used very rarely.
  2. docs:  The list of products that match the search term
  3. numFound: How many products in the catalog match the search term and any filters applied.  This is what is used to communicate to the end user how many products match their search term.
  4. placement:  The name of this placement.
  5. spellchecked: If there was a typo that was auto-corrected by our engine, the corrected term will be specified here.  If no spell correction was needed this value will be empty or 'null'.
  6. facets:  List of all facets that are applicable for the products that match this search term
  7. addtoCartParams: parameters that should be appended to add to cart event firing from product detail page of the search result product. 
  8. links: configured links (URLs) with the search term that was specified the request
    1. banner: link to the banner image that should be displayed along with the search results.
    2. directlink: link to another page where shopper should be asked to follow.
    3. sponsored: link to sponsored content that should be displayed 
facets

facets are returned as part of the placements structure. They power the faceted search navigation experience. 

Facets contains these fields:

1. values : array of possible facet options for a give type

2. filter : filter query that should be used when the shopper selects this facet option. filter query should be passed as it is to the filter parameter of the subsequent search request

3. count : Number of items matching this facet option. In other words, number of items to expect when filter for this facet is applied to the subsequent search request.

4. value : Display value for the facet

5. child : For hierarchical attributes like categories, Find provides a way to let shoppers navigate through the hierarchy by providing immediate next child categories in the facet values. This is invoked by providing higher level category as a filter. For example, filter=categoryId:root will provide 1st level children of root as facets in the search response.

6. Price min - max : For price facets, Find returns min and max price values for the current search results, to be able to power a price selection slider kind of UI control instead of option boxes for each individual price ranges. 

status We always return 200s.  The status object will determine if the request was successfully processed ("OK") or if there was an error ("error").  Callers should check for the "OK" string to verify. 
message If there was an error in the status, then this field will contain information as to why an error occurred.

Fields

Some product attributes shared via the catalog feed have fixed/reserved names and must be described by their canonical name.  The table below describes them.

Name Data Type Description

brand

String The manufacturer brand of this product.  E.g. "Lenovo".

categoryId

List of Strings  The category IDs that this product belongs to.

categoryName

String The category names that this product belongs to.

description

String The product description.

id

String The product ID.  A unique identifier for this product.

name

String The name of the product.

numReviews

Number Total number of reviews for this product.

priceCents

Number The regular price of this product.

rating

Number The average product rating.

releaseDate

Date The date this product was introduced into the catalog.  This attribute allows us to calculate how "new" a product is.

salePriceCents

Number The sale price of this product.

 All other product attributes shared in the feed can be described by the name in the catalog feed that retailer shares with RichRelevance