Documentation

Product Suggestions

Elevate, May 20-22-2025, Miami Beach, Florida

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:
fuzzy
​
Boolean
​
If set to true, fuzzy search is applied on the text to analyze.
Default: false​
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​
Maximum: 100​
searchKeywords.<locale>
​
String
​
The input text provided for the language specified as Locale.
The parameter can be passed multiple times.
staged
​
Boolean
​
If set to true (possible only while using the view_products scope), staged projections is queried.
Default: false​
Response:
200

SuggestionResult

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