Find: Content Search API

Description

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

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

The response is a list of content 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
rows	Integer	Required	Rows describe how many results to return back. If you want to show 20 contents 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
start	Integer	Optional	The starting position of the results you want for the specified query. It's a zero indexed system. it zero by default. 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.

sessionId	String	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
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.
filter	String	Optional	Filter the data based on an attribute value. The attribute should be configured as filterable (in the dashboard) to be used as a filter Filtering is only a match, it only limit the search results to certain values, it doesn't affect scoring. It could be specified multiple times for using multiple filters at the same time. For example: Query -> dress Filter -> Color:red. It only retrieves red dresses, but it doesn't make any of the retrieved documents more important than another ones. Template: filter=attribute_name:attribute_value
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. To return no facets in the response use &facet=0. For a list of all applicable fields "facets" list in the response (see response section down below) . Good tip: Use this parameter to specify the facets you need to improve search performance. Template:facet=attribute_name
sort	String	Optional	Specify how you want to sort the contents. You can instead sort by any content attribute that you specified in your catalog. The attribute should be configured as sortable on the dashboard to sort by it. Also, specify whether you want the sort to be in Ascending or Descending order. Allowed values are: "ASC" or "DESC" Example: sort=name+desc Template:sort=attribute_name [asc\|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
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.
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.
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	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.
ssl	Boolean	Optional	If set to true than clickUrl and searchTrackingUrl are returned with https protocol.

Example Request

https://recs.richrelevance.com/rrserver/api/find/v1/content/<API_KEY>?lang=en&query=1&placement=search_page.content&view=graph&rows=10

Example Response

{
  "request": {
    "apiKey": "dmi_rtea",
    "placements": [
      "search_page.content"
    ],
    "sessionId": "null",
    "userId": "null"
  },
  "placements": [
    {
      "searchTrackingUrl": "",
      "rcs": "eF5j4cotK8lM4TM0tdA11DVkKU32sDBJtDQ2TkzUTUxNMtY1MTM20DVKNU3UNU40tTA1sTAxNU5NBQCGvw3-",
      "docs": [
        {
          "clickUrl": "http://qa.richrelevance.com/rrserver/api/find/v1/track/click/dmi_rtea?a=dmi_rtea&vg=810f60e7-aeb3-4630-5d52-3c594e967767&pti=2&pa=content&hpi=0&stn=PersonalizedContentSearchAndBrowse&stid=195&rti=2&sgs=&uguid=84a933aa-aeb3-4630-2e5a-3a58548453ee&channelId=WEB&s=&pg=-1&page=1&query=1&lang=en&searchConfigId=5b5f8fc946ff25000e2818f3&p=31855722368&ind=0&ct=https%3A%2F%2Fwww.republicoftea.com%2Fthanks-youre-a-peach-gift-tea%2Fp%2Fv20333",
          "score": 14.065722,
          "ASSET_URL": "https://static.trotcdn.com/images/325/V20333.jpg",
          "AREA": "DefaultArea",
          "previewUrl": "https://static.trotcdn.com/images/325/V20333.jpg",
          "name": "find content 1",
          "URL_P__name": "name-default",
          "link": "https://www.republicoftea.com/thanks-youre-a-peach-gift-tea/p/v20333",
          "id": "31855722368",
          "content_region_id": [
            8735210,
            8735211,
            8735209,
            8735208
          ]
        }
      ],
      "numFound": 1,
      "placement": "search_page.content",
      "metrics": {
        
      },
      "spellchecked": null,
      "errors": [
        
      ],
      "facets": [
        {
          "values": [
            {
              "filter": "{!tag=content_name}content_name:\"find\\ content\\ 1\"",
              "count": 1,
              "value": "find content 1",
              "child": null
            }
          ],
          "facet": "name"
        },
        {
          "values": [
            {
              "filter": "{!tag=AREA}AREA:\"DefaultArea\"",
              "count": 1,
              "value": "DefaultArea",
              "child": null
            }
          ],
          "facet": "AREA"
        },
        {
          "values": [
            {
              "filter": "{!tag=content_start_date}content_start_date:\"1532934000000\"",
              "count": 1,
              "value": "1532934000000",
              "child": null
            }
          ],
          "facet": "startDate"
        }
      ]
    }
  ],
  "message": "Session ID should be set",
  "status": "warning"
}

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: 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'. docs: The list of contents that match the search term numFound: How many contetns in the catalog match the search term and any filters applied. This is what is used to communicate to the end user how many contents match their search term. placement: The name of this placement. 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'. facets: List of all facets that are applicable for the contents that match this search term
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.
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 content 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
id	String	The content ID. A unique identifier for this content.
name	String	The name of the content.
content_region_id	List of Integer	Regions Internal Ids.
clickUrl	String	the url of the content.

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