Product Suggestions

The suggestions can be used to implement a basic auto-complete functionality.

The source of data for suggestions is the searchKeyword field in a product (see ProductData).

To be able to use the Product Suggest endpoint, your product catalog needs to be indexed first.

To activate the indexing for your projects, please choose one of the following options:

via API using the Change Product Search Indexing Enabled update action on the Project endpoint.
via the Merchant Center by navigating to Settings > Projects Settings > Storefront search.
via contacting Support on the Support Portal and provide the region, project key(s), and use case(s).

Representations

Suggestion

SuggestionResult

Suggestion

text - String
The suggested text.

SuggestionResult

searchKeywords.{lang}- Array of Suggestion

The result can contain several such pairs, see the product search keywords suggest example.

Suggest query

Endpoint: /{projectKey}/product-projections/suggest
Method: GET
OAuth 2.0 Scopes: view_products:{projectKey}, view_published_products:{projectKey}
Response Representation: SuggestionResult
Query Parameters:

searchKeywords.{lang} - String - Required
Retrieves suggestion text from the SearchKeywords of ProductData in the given language. The language is an IETF language tag. A request can contain several searchKeywords.{lang} parameters for different languages. The input is matched against the tokens defined by the SearchKeyword suggestTokenizer.
fuzzy - Boolean - Optional (Defaults to false)
Whether to use fuzzy search.
limit - Number - Optional
Default is 10 results per language and the maximum is 100 results per language.
staged - Boolean - Optional (Defaults to false)
Whether to search in the current or staged projections.
When using the OAuth 2.0 scope view_published_products, it is not permitted to use staged = true.

Example suggest request

GET /{projectKey}/product-projections/suggest?searchKeywords.en=knife&fuzzy=true&staged=true&limit=5

Product Search Keywords Suggest examples

Consider a product with the following searchKeywords:

{
  "en": [
    {
      "text": "Multi tool"
    },
    {
      "text": "Swiss Army Knife",
      "suggestTokenizer": {
        "type": "whitespace"
      }
    }
  ],
  "de": [
    {
      "text": "Schweizer Messer",
      "suggestTokenizer": {
        "type": "custom",
        "inputs": ["schweizer messer", "offiziersmesser", "sackmesser"]
      }
    }
  ]
}

No tokenizer

GET /{projectKey}/product-projections/suggest?searchKeywords.en=multi will return

{ "searchKeywords.en": [{ "text": "Multi tool" }] }

since multi is a prefix of Multi tool.

GET /{projectKey}/product-projections/suggest?searchKeywords.en=tool returns no results since Multi tool does not have a tokenizer set.

Whitespace tokenizer

GET /{projectKey}/product-projections/suggest?searchKeywords.en=kni will return

{ "searchKeywords.en": [{ "text": "Swiss Army Knife" }] }

since the text Swiss Army Knife uses a whitespace tokenizer and kni is a prefix of 'Knife'.

Custom tokenizer

GET /{projectKey}/product-projections/suggest?searchKeywords.de=offiz will return

{ "searchKeywords.de": [{ "text": "Schweizer Messer" }] }

since the text "Schweizer Messer" uses a custom tokenizer and offiz is a prefix of one of the tokenizer inputs.

Suggestions for two languages

GET /{projectKey}/product-projections/suggest?searchKeywords.de=offiz&searchKeywords.en=multi will return

{
  "searchKeywords.de": [{ "text": "Schweizer Messer" }],
  "searchKeywords.en": [{ "text": "Multi tool" }]
}