Product Suggestions

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.de": [
    {
      "text": "Schweizer Messer"
    }
  ],
  "searchKeywords.en": [
    {
      "text": "Multi tool"
    }
  ]
}

Suggestion

Query Suggestions

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