Predictive search is a powerful feature of our Search API, which provides real-time query suggestions and autocomplete functionality. This document outlines how to use the API to enhance user experience by reducing the number of keystrokes required to reach a product page.


The Predictive Search API requires token-based authentication. Include the X-Storefront-Access-Token header with your API token in the form of <YOUR_LAYERS_TOKEN>.


The request must include the following headers:

  • Content-Type: application/json
  • Accept: application/json

Query Parameters

  • partialQuery (string, required): The partial search term entered by the user for which you want to retrieve autocomplete suggestions.

Making a Request

To fetch predictive search suggestions, you’ll make a GET request to the Search API with the partial query:

curl -X GET '{partialQuery}' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'X-Storefront-Access-Token: {YOUR_LAYERS_TOKEN}'

Response Structure

The response includes an array of matched queries with the text and the number of times the query was searched, as well as the original and normalized versions of the query. Here’s an example:

    "matchedQueries": [
            "query_text": "sup",
            "num_searches": 1
            "query_text": "supreme",
            "num_searches": 11
    "originalQuery": "sup",
    "normalizedQuery": "sup"

The matchedQueries array provides suggestions that can be used to autocomplete the user’s query, improving the search experience by offering relevant alternatives and speeding up the search process.


Predictive search is a key component in creating an intuitive and user-friendly search interface. By implementing this feature, you can significantly improve the efficiency of your search functionality, leading to a more satisfying user experience.