> ## Documentation Index
> Fetch the complete documentation index at: https://docs.uselayers.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Autocomplete: Get Suggestions

> Autocomplete API endpoint returning ranked search-query suggestions and top trending queries as shoppers type into your storefront search bar.

The Autocomplete endpoint returns ranked **query-text suggestions** for a partial search term. It does **not** return products, product previews, or images. Use the [Search](https://docs.uselayers.com/api-reference/search.md) endpoint to fetch products for a chosen suggestion.

When no `query` is provided, the endpoint returns the store's top trending queries (subject to the same brand curation rules as live suggestions).

## Authorization

**X-Storefront-Access-Token** `string` *required*

Token-based authentication header in the form of `<YOUR_LAYERS_TOKEN>`.

## Headers

**Content-Type** `string` *required* (default: application/json)

**Accept** `string` *required* (default: application/json)

## Query parameters

**query** `string`

The partial query you want suggestions for. Maximum 255 characters. Sanitized server-side; queries shorter than 2 characters after sanitization are treated as empty and return trending suggestions instead.

## Response

**matchedQueries** `string[]`

Ranked array of suggestion strings. Prefix matches appear first, followed by non-prefix matches that clear the relevance threshold. Each string is the suggestion text the shopper should see: either the cluster's canonical query or its curated display label when one is configured.

**originalQuery** `string | null`

The `query` value exactly as sent by the client. `null` when the request omits `query` or when the sanitized query is too short.

**normalizedQuery** `string | null`

The lowercased, trimmed form of `originalQuery` used internally for matching. `null` when no query was effectively provided.

**\_meta** `object`

Optional metadata. Present only when a [semantic redirect](https://docs.uselayers.com/platform/semantic-redirects.md) matches the current query.

**Properties**

**redirect** `object`

**Properties**

**url** `string`

The destination URL the storefront should navigate to. Suggestions are still returned alongside the redirect. With the Layers app embed enabled, the Storefront Pixel follows the redirect when the shopper submits the query or clicks its suggestion, so theme code only renders the suggestion list. Headless storefronts without the embed decide whether to follow the redirect immediately or render the suggestion list.

> [!NOTE]
>
> **Semantic Redirects**: When the autocomplete query matches a configured [semantic redirect](https://docs.uselayers.com/platform/semantic-redirects.md) term, either exactly or semantically, the response includes a `_meta.redirect` object with the redirect URL. This lets you redirect users directly from the typeahead experience before they submit a full search.

## Suggestion quality

Layers applies several techniques to keep autocomplete suggestions relevant and concise.

### Regional suggestions

Suggestion candidates can be scoped to the shopper's country before matching runs. Layers resolves the country from IP-based geolocation and applies the store's region mode:

* **Separate suggestions per region** (default): shoppers in each country see suggestions built from that country's own search activity. If a country doesn't yet have enough curated search history to stand on its own, shoppers there receive the shared, store-wide suggestion set instead.
* **One set of suggestions for all shoppers**: every request returns the same store-wide suggestion set, regardless of the shopper's location.

Requests with no resolvable location always receive the store-wide set. Configure the mode in the Layers dashboard under **Settings → Autocomplete**. See [Configure autocomplete curation](https://docs.uselayers.com/help/configuration/configure-autocomplete-curation.md#regional-suggestions) for steps.

### Brand curation

You can layer a natural-language brand prompt on top of the default suggestion pipeline. Layers uses the prompt, together with your store description, to suppress off-brand suggestions and rewrite display labels for customers. Suppressed clusters never appear in `matchedQueries`, and curated clusters return their rewritten text in place of the canonical query. Matching against raw customer queries is unchanged. See [Autocomplete curation](https://docs.uselayers.com/platform/autocomplete-curation.md) for configuration details.

### Stem deduplication

Autocomplete automatically collapses singular and plural variants of the same word into a single suggestion. For example, if your query data contains both "diamond" and "diamonds", only the higher-scoring canonical form is returned. This also applies to other English stem variations like "berry" and "berries" or "long sleeve" and "long-sleeve".

Stem awareness extends to query matching as well. When a shopper types "diamonds", autocomplete finds suggestions containing the singular "diamond" and vice versa, so singular and plural queries produce the same suggestion list.

When multiple suggestions share the same stem, the suggestion with the highest relevance score is kept. Shorter canonical forms (typically the singular) win ties, which keeps the suggestion list clean and predictable.

### Relevance gating

Suggestions that don't closely match the query text are filtered out before results are returned. Prefix matches (where the query is the beginning of a suggestion) always pass through. Non-prefix matches must meet a minimum text-similarity threshold to appear. This prevents semantically distant suggestions from surfacing alongside direct matches.

```json Response theme={null}
{
    "matchedQueries": [
        "sup",
        "supreme"
    ],
    "originalQuery": "sup",
    "normalizedQuery": "sup"
}
```

```json Response (with semantic redirect) theme={null}
{
    "matchedQueries": [
        "support"
    ],
    "originalQuery": "support",
    "normalizedQuery": "support",
    "_meta": {
        "redirect": {
            "url": "https://yourstore.com/pages/contact-us"
        }
    }
}
```

```json Response (no query — trending suggestions) theme={null}
{
    "matchedQueries": [
        "summer dresses",
        "linen shirts",
        "white sneakers"
    ],
    "originalQuery": null,
    "normalizedQuery": null
}
```