Product Suggestions
Suggestions can be used to implement a basic auto-complete functionality for your storefront search.
With a Query Suggestions request you provide some text as input for which the endpoint returns terms that you can use for the full text search on the Product Projection Search API.
Prerequisites
Activated Product Projection Search API
The Product Suggestions feature is not active for the Project by default. If the API is deactivated, the Query Suggestions endpoint returns a SearchDeactivated error. To activate the feature for your Project, activate the Product Projection Search API.
Defined search keywords
The terms returned with the Suggestions are specified in the searchKeyword
field of the ProductData.
Add SearchKeywords together with tokenizers to your Products to get the most relevant Suggestions returned.
Representations
SuggestionResult
/searchKeywords.[a-z]{2}-[A-Z]{2}?/ Array of Suggestion | The result may contain multiple Suggestions identified by their Locale. See Suggestions for two languages. |
{"searchKeywords.de": [{"text": "Schweizer Messer"}],"searchKeywords.en": [{"text": "Multi tool"}]}
Suggestion
text String | The suggested text. |
Query Suggestions
view_products:{projectKey} ,
view_published_products:{projectKey}
region String | Region in which the Project is hosted. |
projectKey String |
|
/searchKeywords.[a-z]{2}(-[A-Z]{2})?/ Any string parameter matching this regular expression | The input text provided for the language specified as Locale. The parameter can be passed multiple times. |
limit Int | Controls how many suggestions per language the SuggestionResult will contain.
The default limit is Default: 10 |
fuzzy Boolean | If set to Default: false |
staged Boolean | If set to Default: false |
application/json
curl --get https://api.{region}.commercetools.com/{projectKey}/product-projections/suggest -i \--header 'Authorization: Bearer ${BEARER_TOKEN}'
{"searchKeywords.de": [{"text": "Schweizer Messer"}],"searchKeywords.en": [{"text": "Multi tool"}]}
Example queries
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"]}}]}
Suggestions for one language
No tokenizer
Imagine we use multi
as input text to get a search term Suggestion. In the SearchKeywords, we have the text "Multi tool"
defined, but no tokenizer assigned to it:
{"en": [{"text": "Multi tool"}]}
The query with searchKeywords.en=multi
returns the following result since multi
is a prefix of Multi tool
:
{ "searchKeywords.en": [{ "text": "Multi tool" }] }
However, the query with searchKeywords.en=tool
does not return any result since Multi tool
does not have a tokenizer assigned in the SearchKeywords that would recognize tool
as part of the word.
Whitespace tokenizer
Now, we look at a search keyword with a whitespace tokenizer assigned to it;
{"en": [{"text": "Swiss Army Knife","suggestTokenizer": {"type": "whitespace"}}]}
The query with searchKeywords.en=kni
returns "Swiss Army Knife"
as the result since the whitespace tokenizer recognizes Knife
as part of the keyword. and kni
is a prefix of Knife
:
{ "searchKeywords.en": [{ "text": "Swiss Army Knife" }] }
Custom tokenizer
Consider following example for the German keyword "Schweizer Messer"
assigned to a custom tokenizer for multiple inputs:
{"de": [{"text": "Schweizer Messer","suggestTokenizer": {"type": "custom","inputs": ["schweizer messer", "offiziersmesser", "sackmesser"]}}]}
The query with searchKeywords.de=offiz
returns "Schweizer Messer"
as result since offiz
is a prefix of one of the tokenizer inputs offiziersmesser
:
{ "searchKeywords.de": [{ "text": "Schweizer Messer" }] }
Suggestions for two languages
You can query for suggestions for two languages in one request by providing searchKeyword
parameters with two different Locales:
searchKeywords.de=offiz&searchKeywords.en=multi
.
The returned SuggestionResult contains suggestions for both languages:
{"searchKeywords.de": [{ "text": "Schweizer Messer" }],"searchKeywords.en": [{ "text": "Multi tool" }]}