# Search Term Suggestions

Suggestions can be used to implement a basic auto-complete functionality for your storefront search.

With a [Query Suggestions](/api/projects/search-term-suggestions.md#query-suggestions) request, you provide some text as input for which the endpoint returns search terms based on the Product's [SearchKeywords](/urn?urn=ctp%3Aapi%3Atype%3ASearchKeywords).
The returned search terms you can use for full text search on the [Product Projection Search API](/api/projects/product-projection-search.md#product-projection-search).

This API does not suggest terms for numerical values or special characters, for example, `24 inch` or `7"`.

This API was previously called Product Suggestions.

The equivalent [GraphQL query](/api/graphql.md#use-search-term-suggestions) is `productProjectionsSuggest`.

## Prerequisites

### Activated Product Projection Search API

The Search Term Suggestions API is not active for the Project by default.
If the API is deactivated, the [Query Suggestions](/api/projects/search-term-suggestions.md#query-suggestions) endpoint returns a [SearchDeactivated](/urn?urn=ctp%3Aapi%3Atype%3ASearchDeactivatedError) error.
To activate this feature for your Project, activate the [Product Projection Search API](/api/projects/product-projection-search.md#activate-the-product-projection-search-api).

### Defined search keywords

The terms returned with the [Suggestions](/api/projects/search-term-suggestions.md#suggestion) are specified in the `searchKeyword` field of the [ProductData](/urn?urn=ctp%3Aapi%3Atype%3AProductData).
Add [SearchKeywords](/urn?urn=ctp%3Aapi%3Atype%3ASearchKeywords) together with [tokenizers](/api/projects/products.md#suggesttokenizer) to your Products to get the most relevant [Suggestions](/api/projects/search-term-suggestions.md#suggestion) returned.

## Representations

#### SuggestionResult

[type definition](/api/projects/search-term-suggestions.md?urn=ctp:api:type:SuggestionResult).

#### Suggestion

[type definition](/api/projects/search-term-suggestions.md?urn=ctp:api:type:Suggestion).

## Query Suggestions

[endpoint definition](/api/projects/search-term-suggestions.md?urn=ctp:api:endpoint:/\{projectKey}/product-projections/suggest:GET).

## Example queries

Consider a [Product](/urn?urn=ctp%3Aapi%3Atype%3AProduct) with the following [SearchKeywords](/urn?urn=ctp%3Aapi%3Atype%3ASearchKeywords):

```json title="Search keywords on ProductData"
{
  "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

If you use `multi` as input text to get a search term Suggestion, and in the SearchKeywords you have the text `"Multi tool"` defined but no tokenizer assigned to it:

```json title="Search keyword"
{
  "en": [
    {
      "text": "Multi tool"
    }
  ]
}
```

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

```json title="Suggestion"
{ "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

Consider a search keyword with a whitespace tokenizer assigned to it:

```json title="Search keyword"
{
  "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`:

```json title="Suggestion"
{ "searchKeywords.en": [{ "text": "Swiss Army Knife" }] }
```

#### Custom tokenizer

Consider the following example for the German keyword `"Schweizer Messer"` assigned to a custom tokenizer for multiple inputs:

```json title="Search keyword"
{
  "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`:

```json title="Suggestion"
{ "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](/api/types.md#locale):
`searchKeywords.de=offiz&searchKeywords.en=multi`.
The returned [SuggestionResult](/api/projects/search-term-suggestions.md#suggestionresult) contains suggestions for both languages:

```json title="Suggestion"
{
  "searchKeywords.de": [{ "text": "Schweizer Messer" }],
  "searchKeywords.en": [{ "text": "Multi tool" }]
}
```

## Related pages

- [Area overview page with navigation](/api.md)
- [Previous page: Product Projection Search](/api/projects/product-projection-search.md)