Skip to main content
RichRelevance

Find: Autocomplete API

Description

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.

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

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.

Syntax: responseStyle=sections

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

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

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

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

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

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

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

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

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

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

{
"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.
  • Was this article helpful?