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.

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

Suggestion

text
String

The suggested text.

Query Suggestions

GET
https://api.{region}.commercetools.com/{projectKey}/product-projections/suggest
OAuth 2.0 Scopes:
view_products:{projectKey}view_published_products:{projectKey}
Path parameters:
region
String

Region in which the Project is hosted.

projectKey
String

key of the Project.

Query parameters:
/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 10 Suggestions per language and the maximum is 100.

Default: 10
fuzzy
Boolean

If set to true, fuzzy search is applied on the text to analyze.

Default: false
staged
Boolean

If set to true (possible only while using the view_products scope), staged projections is queried.

Default: false
Response:
200SuggestionResultasapplication/json
Request Example:cURL
curl --get https://api.{region}.commercetools.com/{projectKey}/product-projections/suggest -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}'
200 Response Example: SuggestionResultjson
{
"searchKeywords.de": [
{
"text": "Schweizer Messer"
}
],
"searchKeywords.en": [
{
"text": "Multi tool"
}
]
}

Example queries

Consider a Product with the following SearchKeywords:

Search keywords on ProductDatajson
{
"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:

Search keywordjson
{
"en": [
{
"text": "Multi tool"
}
]
}

The query with searchKeywords.en=multi returns the following result since multi is a prefix of Multi tool:

Suggestionjson
{ "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;

Search keywordjson
{
"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:

Suggestionjson
{ "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:

Search keywordjson
{
"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:

Suggestionjson
{ "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:

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