Skip to content

POST /suggest

904Labs A.I. for Search offers a suggestion endpoint that can be used to integrate advanced search functionalities in the search box on a client's web app. Specifically, the suggest endpoint provides typeahead (query term suggestions), category suggestions, product suggestions, and filter suggestions. The /suggest endpoint provides one entry point to all these functionalities.

Request

HTTP request

POST https://api.904labs.com/sls/{customer_id}/suggest?q={query}&user_id={user_id}&session_id={session_id}&domain={domain}&locale={locale}&spellcheck={spellcheck}&format={format}&api_key={api_key}

Request attributes

Attribute Type Description
customer_id string (required) Your customer ID

Request parameters

Parameter Type Description
q string (required) The query issued by the user, URL encoded
api_key string (required) Your API key
session_id string (required) The session ID for the user issuing the query
locale string (required) Country and language of the shop/site in ll_TT format, where ll is the language in ISO 639-1 format and TT is the territory in ISO 3166 format (e.g., en_US).
user_id string (optional) The user ID to allow for personalization of results
domain string (optional) A particular domain to narrow the search (e.g., age group, subshop). (Default: default)
spellcheck boolean (optional) Run the user query through spellchecking (true) or not (false). In case spellchecking is done, the spellchecked query is used to fetch the other suggestions. (Default: true)
format string (optional) Formatting of suggestions: dict returns an unsorted dictionary, which allows the client to pick from it. list returns a sorted list of suggestions, which can be used directly as is in the suggest box. (Default: list)
lang string (deprecated) Replaced by locale

Request body

Property name Value Description
filters json (optional) Specific filters that you use for your search engine, and that should be taken into account for suggestions as well.

Example request

import requests as r

headers = {"content-type": "application/json"}
URL_SUGGEST = "https://api.904labs.com/sls/CUSTOMER_ID/suggest"
params = {
    "q": "red ca",
    "session_id": "SESSION_ID",
    "api_key": "APIKEY",
    "spellcheck": True,
    "format": "list",
    "locale": "en_US"
}
payload = {
    "filters": [ {
        "nested": {
          "path": "search_data.string_facet",
          "filter": {
            "bool": {
              "must": [ {
                "term": {
                  "search_data.string_facet.facet-name": "in_stock"
                }
              },
              {
                "term": {
                  "search_data.string_facet.facet-value": True
                }
              } ]
            }
          }
        }
    } ]
}
response = r.post(URL_SUGGEST, headers=headers, params=params, json=payload)

Response

The structure of the response JSON object depends on the setting of the format request URL parameter. The default setting is list.

As list

{
    "query": string, 
    "suggestions": [
        {
            "type": "query",
            "suggestion": string
        }, 
        {
            "type": "filter",
            "suggestion": string, 
            "filter": [
                {
                    "field_name": string, 
                    "field_value": [
                        string
                    ]
                }, 
            ]
        }, 
        {
            "type": "category",
            "suggestion": string, 
            "category": {
                "filter": [
                    {
                        "field_name": string,
                        "field_value": [
                            string
                        ]
                    }, 
                ], 
                "name": string
            }
        },
        {
            "type": "product",
            "suggestion": string, 
            "product": {
                "id": string, 
                "img": string, 
                "title": string, 
                "url": string
            }
        }
    ]
}
Property name Value Description
query string Original user query sent to the /suggest endpoint.
suggestions list List of dictionaries with various suggestions.
suggestions.type string In list format this indicates the suggestion type.
suggestions.suggestion string In case of query suggestions, this parameter contains the suggested query. For other suggestion types, it contains the query term(s) that are used to generate the specific suggestion.
suggestions.filter list List of dictionaries with suggested filters. If multiple filters are present, they should be combined with AND.
suggestions.filter.field_name string Name of the filter's field.
suggestions.filter.field_value list List of field values. When multiple values are present, they should be combined with OR.
suggestions.category.name string Human-readable name of the suggested category (path).
suggestions.category.filter list List of dictionaries with suggested category filters. If multiple filters are present, they should be combined with AND.
suggestions.category.filter.field_name string Name of the filter's field / category.
suggestions.category.filter.field_value list List of field values. When multiple values are present, they should be combined with OR.
suggestions.product.id string ID of the product
suggestions.product.url string URL of product detail page
suggestions.product.img string URL of the product's image
suggestions.product.title string Title of the product

As dict

The returned JSON object for dict formatted output is very similar to the list output. The main difference is that the dictrionary format allows one to refer to individual suggestion types directly. For a description of the returned object, please look at the table above. The only addition is the first_query_suggestion property, which is the most likely query suggestion.

{
    "query": string, 
    "suggestions": {
        "first_query_suggestion" : {
            "type": "query",
            "suggestion": string
        },
        "query_suggestions" : [ 
            {
                "type": "query",
                "suggestion": string
            }
        ],
        "category_suggestions" : [
            {
                "type": "category",
                "suggestion": string, 
                "category": {
                    ...
                }
            }
        ],
        "product_suggestions" : [
            {
                "type": "product",
                "suggestion": string, 
                "product": {
                    ...
                }
            }
        ],
        "filter_suggestions" : [
            {
                "type": "filter",
                "suggestion": string, 
                "filter": [
                    ...
                ]
            }
        ]
    }
}

Example response

The example (partial) query "tui" is suggested to be "tuinset", which is listed in the query type suggestion. This suggested query is subsequently used in retrieving the filter, category, and product suggestions.

{
    "query" : "tui", 
    "suggestions" : [
        {
            "type": "query",
            "suggestion": "tuinset"
        }, 
        {
            "type": "filter",
            "suggestion": "tuinset",
            "filter": [
                {
                    "field_name": "brand", 
                    "field_value": [
                        "Beliani"
                    ]
                }, 
                {
                    "field_name": "category_1", 
                    "field_value": [
                        "Garden"
                    ]
                }, 
                {
                    "field_name": "category_2", 
                    "field_value": [
                        "Furniture"
                    ]
                }
            ]
        }, 
        {
            "type": "category",
            "suggestion": "tuinset",
            "category": {
                "filter": [
                    {
                        "field_name": "category_1",
                        "field_value": [
                            "Garden"
                        ]
                    }, 
                    {
                        "field_name": "category_2", 
                        "field_value": [
                            "Furniture"
                        ]
                    }
                ], 
                "name": "Garden > Furniture"
            }
        },
        {
            "type": "category",
            "suggestion": "tuinset",
            "category": {
                "filter": [
                    {
                        "field_name": "category_1", 
                        "field_value": [
                            "Garden"
                        ]
                    }, 
                    {
                        "field_name": "category_2", 
                        "field_value": [
                            "Sets"
                        ]
                    }
                ], 
                "name": "Garden > Sets"
            }
        }, 
        {
            "type": "product",
            "suggestion": "tuinset",
            "product": {
                "id": "AA-BB-1", 
                "img": "https://images.example-cdn.com/garden/furniture/tuinset-aa-bb.jpg", 
                "title": "Tuinset (black)", 
                "url": "https://www.example.com/garden/furniture/tuinset-black"
            }
        }
    ]
}