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:

Representations

Suggestion

  • text - String
    The suggested text.

SuggestionResult

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