This is the early access documentation preview for Custom Views. This documentation might not be in sync with our official documentation.

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. If indexing is deactivated for your Project, a SearchDeactivated error is returned.

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" }]
}