Autocomplete API

Copy

https://recs.richrelevance.com/rrserver/api/find/v1/autocomplete/<API_KEY>

Returns a list of popular search terms that start with a prefix.

The response is a list of product search terms grouped by Category, Brand, TopTrends, Product, and custom attributes. For more information on the response object, see Example Response #1.

If search terms starting with that prefix are not found, it will return a 200 response with an empty array.

Ensure autocomplete suggestions are in the product catalog index

The findFilter parameter compares all the autocomplete suggestions and ensures that they are available in the product catalog index. This feature compares each term, product, category, and brand to the product catalog and filters, and returns the successful suggestions. Autocomplete and product catalog indexes are built at different times.

Filter autocomplete suggestions by an attribute found in the product catalog index

The autocomplete index is separate from the product catalog index. The autocomplete index supports minimal attributes while the product catalog index can support many custom attributes including those to control which customers can view specific products. Many B2B customers require the ability to filter the suggestions by product custom attributes such as users, groups of users so shoppers are only seeing suggestions that apply to their portfolio. The catalogFq and findFilter parameters work together to meet this requirement.

Parameters

Name	Data Type	Required or Optional	Description
query	String	Required	The text to search for autocomplete suggestions. Example: query=shoes
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.
start	Integer	Required	This is a pagination parameter. Indicates start index of the result set.
rows	Integer	Required	This is a pagination parameter. Indicates total number of items to include in the result set.
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
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 Algonomy in other applications. Example: userId=0982347
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: channelId=CallCenter
log	Boolean	Optional	If set to true, this will log the search request event. The default value is false. In that case analytics and reporting are skipped. Note: Only the values "true" and "false" will work.
region	String	Optional	Region identifier.
filter	String	Optional	Used to specify search filters. Filters that can be used in autocomplete are the type of terms, Example: filter=type:BRAND OR type:CATEGORY Note: Terms are de-duplicated in index time. That means that if you send a request with filter and the term is already present in another type, it will not be returned. Example: Sending a request for "shoe" with "filter=type:CATEGORY" will not return the category "Shoes" if that term is already in another list - For example, TOPTRENDS.
catalogFq		Optional	Required to filter autocomplete suggestions on an attribute from the product catalog. One common use case is when there is an attribute to control which users only have access to specific products. By filtering autocomplete against that product attribute, will ensure that the autocomplete suggestions drive shoppers to products in their portfolio. The product attribute needs to be “filterable”. For streaming customers, check the property definition. For batch Find customers, check the attribute in the portal under Search \| Browse > Search Attributes Configuration. Syntax: catalogFq=<attributeName>:<attributeValue>
findFilter		Optional	Used to invoke the new find filter. It is required if you are using the catalogFq parameter. Syntax: findFilter=true
responseStyle		Optional	Returns a mapped response, where one section includes “suggestions” and other sections include “errors”. This helps in debugging the issues with autocomplete and findFilter. The current default setting returns a JSON with only suggestions. Copy `{ "suggestions" : [<list of suggestions>], "errors" : [ ], "autocompleteDebug" : {debug content }, }`
autocompleteDebug		Optional	Returns detailed information on the autocomplete query including if the findFilter parameter is being used. It is required if you are using the responseStyle parameter. Syntax: autocompleteDebug=all

Example Request #1

Standard autocomplete query with suggestions returned

Copy

https://recs.richrelevance.com/rrserver/api/find/v1/autocomplete/<API_KEY>?lang=en&query=max&log=true&userId=0982347&sessionId=93484&region=abc&channelId=CallCenter

Example Response #1

Copy

[{
"id":"maxi dress",
"terms":"maxi dress",
"type":"TOPTRENDS",
"value":"221"
},{
"id":"maxi",
"terms":"maxi",
"type":"TOPTRENDS",
"value":"77"
},{
"id":"maxi skirt",
"terms":"maxi skirt",
"type":"TOPTRENDS",
"value":"48"
},{
"id":"maxi dresses",
"terms":"maxi dresses",
"type":"TOPTRENDS",
"value":"46"
}]

Example Request #2

With findFilter and catalogFq

Copy

https://recs.richrelevance.com/rrserver/api/find/v1/autocomplete/<API_KEY>?query=glove&lang=en&rows=5&start=0&findFilter=true&catalogFq=userGroup:MEDICAL

Example Response #2

Copy

[
{
"id": "gloves",
"terms": "gloves",
"type": "TOPTRENDS",
"value": "0.048014979144844275"
},
{
"id": "Glove Club",
"terms": "Glove Club",
"type": "BRAND",
"value": "0.012801508689931315"
},
{
"id": "Dash Medical Gloves Inc",
"terms": "Dash Medical Gloves Inc",
"type": "BRAND",
"value": "0.008926678275538827"
},
{
"id": "Smart Glove Corporation",
"terms": "Smart Glove Corporation",
"type": "BRAND",
"value": "0.0010050629581682682"
},
{
"id": "1389870",
"terms": "Digitsafety HaloKote Glove",
"type": "PRODUCT",
"value": "2.550155389847699E-4"
}
]

Example Request #3

With findFilter, catalogFq, and responseStyle=sections

Copy

https://recs.richrelevance.com/rrserver/api/find/v1/autocomplete/<API_KEY>?query=glove&lang=en&rows=5&start=0&responseStyle=sections&findFilter=true&catalogFq=userGroup:MEDICAL

Example Response #3

Copy

{
"suggestions": [
{
"id": "gloves",
"terms": "gloves",
"type": "TOPTRENDS",
"value": "0.048014979144844275"
},
{
"id": "Glove Club",
"terms": "Glove Club",
"type": "BRAND",
"value": "0.012801508689931315"
},
{
"id": "Dash Medical Gloves Inc",
"terms": "Dash Medical Gloves Inc",
"type": "BRAND",
"value": "0.008926678275538827"
},
{
"id": "Smart Glove Corporation",
"terms": "Smart Glove Corporation",
"type": "BRAND",
"value": "0.0010050629581682682"
},
{
"id": "1389870",
"terms": "Digitsafety HaloKote Glove",
"type": "PRODUCT",
"value": "2.550155389847699E-4"
}
],
"errors": [],
"autocompleteDebug": {},
"timings": {
"find.total": 22
}
}

Example Request # 4

Standard autocomplete query with autocompleteDebug=all

Copy

https://recs.richrelevance.com/rrserver/api/find/v1/autocomplete/<API_KEY>?query=glove&lang=en&rows=5&start=0&responseStyle=sections&autocompleteDebug=all

Example Response #4

Copy

{
"suggestions": [
{
"id": "gloves",
"terms": "gloves",
"type": "TOPTRENDS",
"value": "0.048014979144844275"
},
{
"id": "Glove Club",
"terms": "Glove Club",
"type": "BRAND",
"value": "0.012801508689931315"
},
{
"id": "Dash Medical Gloves Inc",
"terms": "Dash Medical Gloves Inc",
"type": "BRAND",
"value": "0.008926678275538827"
},
{
"id": "Smart Glove Corporation",
"terms": "Smart Glove Corporation",
"type": "BRAND",
"value": "0.0010050629581682682"
},
{
"id": "1389870",
"terms": "Digitsafety HaloKote Glove",
"type": "PRODUCT",
"value": "2.550155389847699E-4"
}
],
"errors": [],
"autocompleteDebug": {
"autocompleteSearchServiceDebug": {
"message": []
},
"searchClientRequest": {
"clientRequest": "GET http://10.3.252.38:80/searchservice/query/1741/autocomplete?q=glove&noActivityBoost=-1.0&start=0&autocompleteDebug=all&lang=en&rows=5&eq=%7B%22id%22%3A1461321668%2C%22title%22%3A%22Default%22%2C%22enabled%22%3Atrue%2C%22enabled_time%22%3A12345.6789%2C%22fields%22%3A%5B%7B%22field%22%3A%22TOPTRENDS%22%2C%22boost%22%3A1%7D%2C%7B%22field%22%3A%22PRODUCT%22%2C%22boost%22%3A1%7D%2C%7B%22field%22%3A%22CATEGORY%22%2C%22boost%22%3A1%7D%2C%7B%22field%22%3A%22BRAND%22%2C%22boost%22%3A1%7D%5D%7D HTTP/1.1",
"clientHeaders": "[User-Agent: EmpathyBroker HTTPClient, Content-Charset: UTF-8, Accept-Charset: UTF-8, Accept-Encoding: gzip]"
}
},
"timings": {
"find.total": 12
}
}

Example Request #5

With autocompleteDebug=all, findFilter, and catalogFq

Copy

https://recs.richrelevance.com/rrserver/api/find/v1/autocomplete/<API_KEY>?query=glove&lang=en&rows=5&start=0&responseStyle=sections&autocompleteDebug=all&findFilter=true&catalogFq=userGroup:MEDICAL

Example Response #5

Copy

{
"suggestions": [
{
"id": "gloves",
"terms": "gloves",
"type": "TOPTRENDS",
"value": "0.048014979144844275"
},
{
"id": "Glove Club",
"terms": "Glove Club",
"type": "BRAND",
"value": "0.012801508689931315"
},
{
"id": "Dash Medical Gloves Inc",
"terms": "Dash Medical Gloves Inc",
"type": "BRAND",
"value": "0.008926678275538827"
},
{
"id": "Smart Glove Corporation",
"terms": "Smart Glove Corporation",
"type": "BRAND",
"value": "0.0010050629581682682"
},
{
"id": "1389870",
"terms": "Digitsafety HaloKote Glove",
"type": "PRODUCT",
"value": "2.550155389847699E-4"
}
],
"errors": [],
"autocompleteDebug": {
"contextDebug": {},
"autocompletePluginDebug": {
"query": {
"defType": "edismax",
"qf": "search_Manufacturer_Name search_product_num_reviews search_product_category_name search_Manufacturer_Code search_product_brand search_product_description search_product_name search_product_rating search_Catalog search_product_external_id search_product_category_external_id",
"q.op": "AND",
"fq": "fms_Catalog:MEDICAL",
"productExternalIdField": "fs_product_external_id",
"findFilter": true
},
"explain": {
"autocompleteFindFilter": {
"fieldSchema": [
"{TOPTRENDS=toptrends, CATEGORY=fms_product_category_name, PRODUCT=products, BRAND=fs_product_brand}"
],
"catalogSolrQuery": [
"q=*&rows=0&qt=/findFilter&findFilter.entity=fms_product_category_name:\"FOOD+GLOVE\"&findFilter.entity=fs_product_brand:\"Glove+Club\",\"Smart+Glove+Corporation\",\"Dash+Medical+Gloves+Inc\",\"Sri+Trang+Gloves+(thailand)\",\"Best+Glove\"&findFilter.entity=toptrends:\"gloves\"&findFilter.entity=products:1520042,1389870,5702235,4998918,1354845&defType=edismax&qf=search_Manufacturer_Name+search_product_num_reviews+search_product_category_name+search_Manufacturer_Code+search_product_brand+search_product_description+search_product_name+search_product_rating+search_Catalog+search_product_external_id+search_product_category_external_id&q.op=AND&fq=fms_Catalog:MEDICAL&productExternalIdField=fs_product_external_id&findFilter=true"
]
}
},
"timing": {
"autocompleteFindFilter": {
"buildQuery": 0,
"findFilterProcess.catalogSolrCall": 5,
"findFilterProcess": 5,
"totalAutocompleteFilterComponent": 7
}
},
"counter": {},
"message": {}
},
"autocompleteSearchServiceDebug": {
"message": []
},
"searchClientRequest": {
"clientRequest": "GET http://10.3.252.38:80/searchservice/query/1741/autocomplete?q=glove&findFilter=true&noActivityBoost=-1.0&start=0&autocompleteDebug=all&lang=en&rows=5&catalogParams=%7B%22fq%22%3A%5B%22Catalog%3AMEDICAL%22%5D%7D&eq=%7B%22id%22%3A1461321668%2C%22title%22%3A%22Default%22%2C%22enabled%22%3Atrue%2C%22enabled_time%22%3A12345.6789%2C%22fields%22%3A%5B%7B%22field%22%3A%22TOPTRENDS%22%2C%22boost%22%3A1%7D%2C%7B%22field%22%3A%22PRODUCT%22%2C%22boost%22%3A1%7D%2C%7B%22field%22%3A%22CATEGORY%22%2C%22boost%22%3A1%7D%2C%7B%22field%22%3A%22BRAND%22%2C%22boost%22%3A1%7D%5D%7D HTTP/1.1",
"clientHeaders": "[User-Agent: EmpathyBroker HTTPClient, Content-Charset: UTF-8, Accept-Charset: UTF-8, Accept-Encoding: gzip]"
}
},
"timings": {
"find.total": 25
}
}

Field	Description
id	Identifier for the autocomplete suggestion.
terms	The autocomplete word suggestion.
type	Type of the suggestion. Currently supported is "TOPTRENDS".
value	Popularity score of the suggestion.