Search API: Catalog Search

Our Search API allows for comprehensive searches across your product catalog. This document provides guidance on how to construct search queries and understand the response structure from the API.

​

Authorization

Access to the Search API requires an X-Storefront-Access-Token. Pass your API token in the header to authenticate your requests.

​

Headers

Include the following headers in your request:

• X-Storefront-Access-Token: {token}
• Content-Type: application/json
• Accept: application/json

​

Path Parameters

• searchQuery (string, required): The URL-encoded search query for the products you are looking for.

​

Body Parameters

• filter_group (object): A group of (filter conditions)[/engine/filtering] using various operators.
• pagination (object): Specifies the page number and limit for pagination.
• sort_order_code (string): The sort order for the results.
• facets (array of strings): List of facets to include in the response.
• retrieveFacetCount (boolean): If the count of each facet value should be calculated.
• identity (object): Information used to current identify the customer/session.
• context (object): Anonymous contextual information of the session/customer.
• attributes (array of strings): Additional attributes to include in the response.

​

Making a Request

Here’s how to make a POST request to the Search API API:

curl -X POST 'https://app.uselayers.com/api/storefront/v1/search/{searchQuery}/execute' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'X-Storefront-Access-Token: {YOUR_LAYERS_TOKEN}' \
-d '{
    "pagination": {
        "page": 1,
        "limit": 20
    },
    "userToken": "user_token_string",
    "attributes": ["title", "tags"]
}'

​

Response Structure

The API response will include an array of product objects, total results, pagination details, and optionally, facets. Here’s a snippet of the response:

{
    "results": [
        {
            "id": 44370,
            "title": "Supreme Pouch",
            "body_html": "<p>Featuring iconic Supreme branding...</p>",
            "vendor": "SUPREME",
            ...
        },
        ...
    ],
    "totalResults": 1000,
    "page": 1,
    "totalPages": 50,
    ...
}

​

Conclusion

Utilizing the Search API enables you to execute complex searches and deliver precise results to your users. By applying filters, sorting, and pagination, you can tailor the search experience to meet the needs of your storefront and enhance user engagement.