Skip to main content
RichRelevance

Find: Search API

Description

GET http://recs.richrelevance.com/rrserver/api/find/v1/<API_KEY> or GET http://integration.richrelevance.com/rrserver/api/find/v1/<API_KEY>

Note:- If you are making the Search API requests directly from the web browsers, then you are advised to upgrade the API endpoint to our new First party data capture domain https://recs.algorecs.com in place of https://recs.richrelevance.com. Please work with your algonomy consultant to configure the click URLs to also point to https://recs.algorecs.com

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

Required parameters are followed by the optional parameters in alphabetical order

Name Data Type Required or Optional Description

lang

String Required Recommended to use the two character ISO code such as "en" for english.  Or use codes used in the feed or in the streaming catalog API. 

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

query

String Required

The text to search.  

Example: query=shoes

There is a limit to the size of a query.  It is currently limited to 75 characters. 

rows

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

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.

      The Following parameters are all optional

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

 Channel ID is used by some Algonomy reports to differentiate channels such as mobile or desktop.  Example values are: WEB, WEB_PHONE, WEB_TABLET.  It can be any API client key that an Algonomy consultant has set up for a customer.  

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".

facetDepth Integer Optional

Controls the number of category levels returned in the Category Facet filter.

facetDepth < 0 - Depth parameter is not considered, Standard behavior is applied, i.e. only the top level is returned on the first request and the children are only returned after the top level selection.

facetDepth == 0 - Return no categories to filter.

facetDepth > 0 - The category depth is built until max depth value level or the depth specified in the parameter is reached. Example: facetDepth=5 will return 5 depth level if the category hierarchy has all that levels. If the hierarchy has only 3 levels, then only 3 depth level will be returned.

facet.limit Integer Optional

Default value = 100
Can be a +/- integer value
 
A negative value means that Solr will return unlimited number of constraint counts.
 
More information :
https://lucene.apache.org/solr/guide/6_6/faceting.html#Faceting-Thefacet.limitParameter

facet.limit is only applied to the following responseStyles:  fullResponse and facetsOnly.  

 

NOTE: facetDepth has priority over facet.limit and facet.mincount. When facetDepth is present, facet.limit and facet.mincount are ignored for category field (product_category_name)

facet.mincount Integer Optional

Default value = 0
Can be an integer value.
 
More information :
 
https://lucene.apache.org/solr/guide/6_6/faceting.html#Faceting-Thefacet.mincountParameter

NOTE: facetDepth has priority over facet.limit and facet.mincount. When facetDepth is present, facet.limit and facet.mincount are ignored for category field (product_category_name)

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"

Another filter example with AND and OR:

filter={!tag=material q.op=OR}material:("Leather" OR "Cotton").

The "tag"  filter syntax is used return all the different options for a facet even after filtering. 

findCallType String Optional

Specifies the call type from the client. Default is 'direct'.

direct - If log is true, record the search request event within the analytics system and also forward the search request event to the real time statistics service.

overlay - If log is true, record the search request event within the analytics system, but do not forward the search request event to the real time statistics service. In that case, the searchTrackingUrl should be used to provide real time statistics.

fl String Optional

Field List

The field list parameter limits the information included in a result set to a specified list of fields. The result set will only include the fields specified in the field list plus id and score (which are always returned). Each field must be "storable" or its values won't be returned.  The default is to return all storable fields.

The field list is specified as a comma-separated list of field names. 

Example: fl=size,color      will return:  id  score  size color

If blank, wildcard or null are used, the following will occur:

fl=   (blank)  Returns all storable fields

fl=*   Returns all storable fields

fl=null    No fields are returned

Note:

To return clickURL, please use linkID.  Using linkId will return both the clickURL and linkID.

clickURL is a derived attribute and doesn't have search attributes associated with it such as "storable". 

Example:

Example: fl=size,color,linkId      will return:  id  score  size color linkID  clickURL

log

Boolean Optional

If set to true this will log the search request event for analytics.  The default behavior is for this to be false.

NOTE: Only the values "true" and "false" will work.

mm Integer Optional  Minimum Match
 
The valid values for mm (minimum match) with example param in solr are as :
Positive integer 3
Negative integer -2
Percentage 75%
Negative percentage -25%
An expression 3<90%
Multiple conditional expressions involving > or < signs 2<-25% 9<-3
 
More information : https://lucene.apache.org/solr/guide/6_6/the-dismax-query-parser.html#TheDisMaxQueryParser-Themm_MinimumShouldMatch_Parameter)
ngramSearch Boolean Optional

N-grams are like a sliding window that moves across a word - a continuous sequence of characters of a specified length which in Find is defaulted to 1.  Ngram search is often used with an auto-complete/type ahead feature. For example, as a shopper types each character in the search box, there is a match based on the characters entered.  Some Find customers use the Find API for auto-complete of products instead of the autocomplete API.  It is important for them to be able to set ngramSearch=true as part of the Find query.   It is recommended to set to ngram=false for general product queries. 

There can be a system wide setting for ngramSearch in the site configuration which an Algonomy consultant sets up.  If it is not set up in the site configuration, the default is true. 

This parameter will over-ride the setting in the site configuration as well as the default value.

ngramSearch=true/false. 

 

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

Algonomy Cookie String. This is the encrypted Algonomy cookie for the user associated with the API request. It should be passed exactly as it was received in a prior API response.

Clients should ensure to preserve the 'rcs' value just as it was served. The 'rcs' parameter is always alphanumeric and case-sensitive, with the token value including a mix of uppercase letters, lowercase letters, and numbers.

Note: The 'rcs' parameter allows merchants to effectively provide the Algonomy platform access to a user's Algonomy browser cookie by acting as a cookie proxy (or cookie pass-through). This process involves the merchant reading and writing a user's Algonomy browser cookie and passing it to and from Algonomy via the server-side API.

region

String Optional Region Identifier
responseStyle String Optional

The responseStyle parameter controls the result set that is returned.  By default all fields which are tagged as "storable" are returned as well as facets (facetable).  Personalization and boosts will also be applied if they are setup and turned on.  The responseStyle parameter has a number of options which are detailed below.

fullResponse - Default. Result set limit is 512 rows.

idAndScores  - Returns just the product Ids and scores. The result set limit is up to 10,000.

facetsOnly - Returns just facets and not product or content.  There is also no limit on facets being returned. However the default number of items returned within a facet is 100 and can be controlled by the facet.limit parameter.   Since products and content are not returned, the rows parameter is automatically set to 0.  There is no need to provide the rows parameter in a facetsOnly query.  

productsOnly - Returns products only. Does not return facets and also does not apply personalization, boosts, links, merchandising rules or spell check.  One use case is when personalization is not required and the customer wants to display "new" products and can sort by date.   The purpose is to only bring back the required information and to avoid unnecessary processing.

 

Example of idAndScores: 

    Request: https://...start=0&rows=10000&facet=0&query=phone&responseStyle=idAndScores

Response:

....{

     "docs": [

        {   "score": 1,

           "id": "58481" }

......}

       

 

sessionId String Required

Identifies a single visit by a shopper.  Sessions are used by behavioral models (to scope user behavior in a shopping session.) and reporting metrics.

Example: sessionId=93484

sort

String Optional

Specify how you want to sort a result list of either products or reference content.  The default is a personalized sort based on "score" (sort=score desc). You can instead sort by any attribute that you specified in the search attributes to be sortable.  For a list of all applicable fields go to the "search attributes configuration" in the portal. 

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_effectiveprice_cents (Combined price and sale 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".  One must be specified.

Example: sort=product_release_date desc

You can specify more than one field, and the field name can have spaces. You can also still have the score as the primary sort followed by a secondary sort as in this example:

sort=score desc, field name asc

Note: Multi-value attributes are not sortable.  

If the sort parameter is not correct the default will be used which is "score desc". 

 

spellcheck string optional

Find will spellcheck a query term when the the initial query has 0 results.   It then executes a second query using the recommended spellchecked term. The spellcheck is based on all indexed searchable attributes except for wisdom of crowd attributes and product_external_id. 

The default is "jaro" which is a similarity algorithm to compare short strings. 

The following spellcheck options are provided in order to return the best suggested term(s) and meet customer expectations. 

     jaro - default, JaroWinklerDistance is a similarity algorithm to compare short strings. 

     off - spellcheck is turned off, useful when the query is a bar code or other product code 

     hits - return the suggested term that has the most hits

     suggest - a list of suggestions is returned and is useful when implementing "did you mean". 

 

Below are further details and examples.

jaro   - default - not explicitly provided in query

If the spellcheck parameter is not explicitly set, the "spellchecked" field is returned.

query=seattle1
Response will include: 

"spellchecked" : "seattle"

jaro - parameter provided in query - equivalent result to "query=seattle1".

Note that the "spellcheck" parameter will provide the type of spellcheck and the suggested term. 

query=seattle1&spellcheck=jaro
Response will include:

"spellchecked" : "seattle"
"spellcheck" : {
  "spellcheckType" : "jaro"
  "spellchecked" : "seattle"
}

off

query=seattle1&spellcheck=off
Response -  "docs" is empty

"spellcheck" : {
  "spellcheckType" : "off"
}

 

hits  - see the "suggest" list below to understand why "settler" is returned

query=seattle1&spellcheck=hits
Response will include: 

"spellchecked" : "settler"
"spellcheck" : {
  "spellcheckType" : "hits"
  "spellchecked" : "settler"
}

suggest

A set of suggested terms are returned that could be used for "did you mean" and to build an alternate query. This option does not automatically execute a second query as is the case for "jaro" and "hits".   Two lists are returned:  "spellcheckSuggestions" and  "suggestionsWithHits"  (number of hits  for suggested terms is provided).  

query=seattle1&spellcheck=suggest
Response - "docs" is empty 

"spellcheck" : {
  "spellcheckSuggestions" : {
    "seattle1" :  ["seattle", "seat tl e1", "settler"]
  },
  "suggestionsWithHits": {"seattle":8,  "settler":20},
  "spellcheckType": "suggest"
}

suggest - multiple search terms

query=seattle1 washington1&spellcheck=suggest
Response -  "docs" is empty

"spellcheck" : {
  "spellcheckSuggestions" : {
    "seattle1" :  ["seattle", "seat tl e1", "settler"]
    "washington1" :  ["washington", "washing to n1"]
  },
  "suggestionsWithHits": {"seattle washington":8},
  "spellcheckType": "suggest"
}
ssl Boolean Optional If set to true, then clickUrl and searchTrackingUrl are returned with https protocol.
tie Double Optional

By default the score for each item in a result set is based on the "max" score from one field (plus personalization, boosts etc also play a role).  Often many results will have the same score.  "Tie" is a Solr parameter which takes into account the hits on other fields.  It applies the following calculation:

score = [score of the top scoring subquery] + tie * (sum of other hitting subqueries)

It is recommended to set  "tie" to a low value 0.1 in order that the sum of the other fields doesn't over power the key field with the most hits.  Values can range from 0.0 to 1.0 with the default set to 0.0

"tie" can be a parameter in a Find API query or in the search configuration in the portal.  If in the Find API, it will over-ride the value in the search configuration portal. 

Example Query: ...query=shoes&rows=15&tie=0.1

Further details: https://lucene.apache.org/solr/guide/6_6/the-dismax-query-parser.html#TheDisMaxQueryParser-Thetie_TieBreaker_Parameter

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, search results will be based on session based history (sessionId) and previous view/purchase behavior through the rcs parameter/cookie implementation.  The search results will still take Wisdom of the Crowd behavior into account.

Example Request

http://recs.richrelevance.com/rrserver/api/find/v1/<API_KEY>?query=shoes&lang=en&sessionId=sess456&userId=u789&placement=search_page.search1&start=0&rows=20

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",
         "errors":[],
         "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 real time search request statistics within the Overlay client-side application.  This URL should be invoked by the Overlay application. At the same time, the Overlay application issues search requests with findCallType = 'overlay'.
  2. docs:  The list of products that match the search term - 

    NOTE: if the clickUrl is used directly on the product and requires the redirect to the product page  the parameter &redirect=true needs to be added to each clickUrl

  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 
errors Reported errors that occurred while processing the request.
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

  • Was this article helpful?