Search API: Semantic Catalog Search

curl --request POST \
  --url https://app.uselayers.com/api/storefront/v1/search/{searchQuery}/execute \
  --header 'Accept: <accept>' \
  --header 'Content-Type: <content-type>' \
  --header 'X-Storefront-Access-Token: <x-storefront-access-token>' \
  --data '{
  "attributes": [
    "<string>"
  ],
  "tuning": {
    "textualWeight": 123,
    "visualWeight": 123,
    "multipleFactor": 123,
    "minimumMatch": 123
  },
  "filter_group": {},
  "pagination": {
    "page": 123,
    "limit": 123
  },
  "facets": [
    "<string>"
  ],
  "retrieveFacetCount": true,
  "includeFacetRanges": true,
  "identity": {
    "sessionId": "<string>",
    "customerId": "<string>"
  },
  "context": {
    "path": "<string>",
    "referrer_path": "<string>",
    "marketing_source": "<string>",
    "marketing_medium": "<string>",
    "marketing_campaign": "<string>",
    "marketing_term": "<string>",
    "marketing_content": "<string>",
    "cart_empty": true,
    "cart_value": 123,
    "num_cart_items": 123,
    "signed_in": true,
    "num_orders": 123,
    "geo_city": "<string>",
    "geo_state": "<string>",
    "geo_country": "<string>"
  }
}'

{
    "results": [
        {
            "id": 7003338965178,
            "title": "SUPREME SEALLINE SEE POUCH SMALL",
            "body_html": "The Supreme Sealline See Pouch Small is a versatile and waterproof storage solution that seamlessly marries utility and style. With its clear window for easy visibility and the iconic Supreme branding, it's a sought-after accessory for those who appreciate keeping their essentials dry while making a fashion statement, whether at the beach or in the city..",
            "vendor": "SUPREME",
            "product_type": "Accessories",
            "created_at": 1644047925,
            "handle": "supreme-pouch-44370ss18a32-sm",
            "updated_at": 1698280024,
            "published_at": 1644047925,
            "tags": [
                "consignment",
            ],
            "images": [
                {
                    "alt": "SUPREME POUCH",
                    "src": "https://cdn.shopify.com/s/files/1/0588/3677/9194/products/ss18_supreme_tnf_pouch_blk_2-l_5fb1316e-22f7-4702-9953-57f3fbdda5be.jpg?v=1644047927",
                    "width": 800,
                    "height": 534,
                    "variant_ids": []
                }
            ],
            "metafields": {
                "product": {
                    "alias": "SEALLINE SEE POUCH SMALL",
                    "colorway": "BLACK",
                    "styleCode": "SS18A30 BLACK",
                    "yearOfRelease": 2018,
                    "searchColor": [
                        "black"
                    ]
                }
            },
            "available": true,
            "price_range": {
                "from": 30,
                "to": 30
            }
        }
    ],
    "totalResults": 1000,
    "page": 1,
    "totalPages": 20,
    "facets": {
        "vendor": {
            "ADIDAS": 30,
            "JORDAN": 336,
            "NEW BALANCE": 15,
            "NIKE": 384,
            "REEBOK": 4,
            "SUPREME": 624,
            "VANS": 32
        }
    },
    "attributionToken": "2y10smI2dB7XZXXFJsLUELltgueq8NRdcRD3U8djkLqxQmaVMvg1lSCf2"
}

POST

{searchQuery}

execute

Search API: Semantic Catalog Search

curl --request POST \
  --url https://app.uselayers.com/api/storefront/v1/search/{searchQuery}/execute \
  --header 'Accept: <accept>' \
  --header 'Content-Type: <content-type>' \
  --header 'X-Storefront-Access-Token: <x-storefront-access-token>' \
  --data '{
  "attributes": [
    "<string>"
  ],
  "tuning": {
    "textualWeight": 123,
    "visualWeight": 123,
    "multipleFactor": 123,
    "minimumMatch": 123
  },
  "filter_group": {},
  "pagination": {
    "page": 123,
    "limit": 123
  },
  "facets": [
    "<string>"
  ],
  "retrieveFacetCount": true,
  "includeFacetRanges": true,
  "identity": {
    "sessionId": "<string>",
    "customerId": "<string>"
  },
  "context": {
    "path": "<string>",
    "referrer_path": "<string>",
    "marketing_source": "<string>",
    "marketing_medium": "<string>",
    "marketing_campaign": "<string>",
    "marketing_term": "<string>",
    "marketing_content": "<string>",
    "cart_empty": true,
    "cart_value": 123,
    "num_cart_items": 123,
    "signed_in": true,
    "num_orders": 123,
    "geo_city": "<string>",
    "geo_state": "<string>",
    "geo_country": "<string>"
  }
}'

{
    "results": [
        {
            "id": 7003338965178,
            "title": "SUPREME SEALLINE SEE POUCH SMALL",
            "body_html": "The Supreme Sealline See Pouch Small is a versatile and waterproof storage solution that seamlessly marries utility and style. With its clear window for easy visibility and the iconic Supreme branding, it's a sought-after accessory for those who appreciate keeping their essentials dry while making a fashion statement, whether at the beach or in the city..",
            "vendor": "SUPREME",
            "product_type": "Accessories",
            "created_at": 1644047925,
            "handle": "supreme-pouch-44370ss18a32-sm",
            "updated_at": 1698280024,
            "published_at": 1644047925,
            "tags": [
                "consignment",
            ],
            "images": [
                {
                    "alt": "SUPREME POUCH",
                    "src": "https://cdn.shopify.com/s/files/1/0588/3677/9194/products/ss18_supreme_tnf_pouch_blk_2-l_5fb1316e-22f7-4702-9953-57f3fbdda5be.jpg?v=1644047927",
                    "width": 800,
                    "height": 534,
                    "variant_ids": []
                }
            ],
            "metafields": {
                "product": {
                    "alias": "SEALLINE SEE POUCH SMALL",
                    "colorway": "BLACK",
                    "styleCode": "SS18A30 BLACK",
                    "yearOfRelease": 2018,
                    "searchColor": [
                        "black"
                    ]
                }
            },
            "available": true,
            "price_range": {
                "from": 30,
                "to": 30
            }
        }
    ],
    "totalResults": 1000,
    "page": 1,
    "totalPages": 20,
    "facets": {
        "vendor": {
            "ADIDAS": 30,
            "JORDAN": 336,
            "NEW BALANCE": 15,
            "NIKE": 384,
            "REEBOK": 4,
            "SUPREME": 624,
            "VANS": 32
        }
    },
    "attributionToken": "2y10smI2dB7XZXXFJsLUELltgueq8NRdcRD3U8djkLqxQmaVMvg1lSCf2"
}

Authorization

X-Storefront-Access-Token

string

required

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

Headers

Content-Type

string

default:"application/json"

required

string

default:"application/json"

required

Path Parameters

searchQuery

string

required

The url-encoded search query.

Body

attributes

string[]

Product attributes to include in the Response. By default all attributes are included in the response.

tuning

object

Parameters to fine-tune the search results.

Show Properties

textualWeight

decimal

Weight given to textual similarity (0-1). Must be provided together with visualWeight.

visualWeight

decimal

Weight given to visual similarity (0-1). Must be provided together with textualWeight.

multipleFactor

integer

Multiplier applied to the search results.

minimumMatch

decimal

Minimum match score threshold (0-1) for including results.

filter_group

object

Refer to our dedicated Filter Expressions guide to learn more about filter expressions.

pagination

Pagination Object

Show pagination

page

int

The current page of results to fetch.

limit

int

The max results to fetch per page

facets

string[]

Facets to be included.

retrieveFacetCount

boolean

If the count of each facet value should be calculated

includeFacetRanges

boolean

If you want a min/max range for numeric facets such as price.

identity

object

Information used to current identify the customer/session.

Show Properties

sessionId

string

The session ID of the user.

customerId

string

The customer ID of the user.

context

object

Anonymous contextual information of the session/customer.

Show Properties

path

string

The path of the page the user is on (e.g., /collections/all-products).

referrer_path

string

The referrer path of the previous page the user visited.

marketing_source

string

The source of the UTM tracking for the current session.

marketing_medium

string

The medium of the UTM tracking (e.g., email, CPC).

marketing_campaign

string

The campaign associated with the UTM tracking.

marketing_term

string

The term or keyword used in UTM tracking.

marketing_content

string

The content description used in UTM tracking.

cart_empty

boolean

Indicates whether the user’s cart is empty.

cart_value

number

The total value of the items in the user’s cart.

num_cart_items

integer

The number of items in the user’s cart.

signed_in

boolean

Indicates whether the user is signed in.

num_orders

integer

The total number of orders made by the user.

geo_city

string

The city associated with the user’s context.

geo_state

string

The state or province associated with the user’s context.

geo_country

string

The country associated with the user’s context.

Response

results

Array of Objects

Show Properties

number

The unique identifier of the product.

title

string

The title of the product.

body_html

string

The HTML content describing the product.

vendor

string

The vendor of the product.

product_type

string

The type of the product.

created_at

number

The timestamp when the product was created.

handle

string

The handle of the product.

updated_at

number

The timestamp when the product was updated.

published_at

number

The timestamp when the product was published.

category

Object

The Shopify Product Taxonomy Category of the product.

Show Properties

name

string

The name of the category leaf.

full_name

string

The full name of the category.

string

The ID of the category.

is_leaf

boolean

Is the category a root category.

is_root

boolean

Is the category a root category.

first_or_matched_variant

Object

The first available variant (depending on OOS settings) or the variant matched with a filter or search query.

Show Properties

number

The ID of the variant.

title

string

The title of the variant.

available

boolean

The availability of the variant.

sku

number

The sku of the variant.

price

string

The price of the variant.

compare_at_price

string

The compare at price of the variant.

metafields

Object

The metafields of the variant.

selected_options

Array of Objects

The selected options of the variant.

Show Properties

name

string

The name of the option.

value

string

The value of the option

option_value

object

The linked metafield of the option.

position

number

The sku of the variant.

featured_media

Object

The featured media of the product.

Show Properties

mediaContentType

string

The type of media.

alt

string

The alt text of the image.

src

string

The src of the image.

width

number

The width of the image.

height

number

The height of the image.

featured_media

Object

The featured media of the product.

Show Properties

mediaContentType

string

The type of media.

alt

string

The alt text of the image.

src

string

The src of the image.

width

number

The width of the image.

height

number

The height of the image.

available

boolean

The availability of the product.

price_range

Object

The price range of the product.

Show Properties

from

number

The starting price of the product.

number

The ending price of the product.

totalResults

number

The total number of results.

page

number

The current page number.

totalPages

number

The total number of pages.

attributionToken

string

The attribution token.

facetRanges

object

If includeFacetRanges is true then an object with keys of the facet attribute code and value is an object with min/max.

facets

object

If retrieveFacetCount is true then an object with keys and values of the specified attributes.

{
    "results": [
        {
            "id": 7003338965178,
            "title": "SUPREME SEALLINE SEE POUCH SMALL",
            "body_html": "The Supreme Sealline See Pouch Small is a versatile and waterproof storage solution that seamlessly marries utility and style. With its clear window for easy visibility and the iconic Supreme branding, it's a sought-after accessory for those who appreciate keeping their essentials dry while making a fashion statement, whether at the beach or in the city..",
            "vendor": "SUPREME",
            "product_type": "Accessories",
            "created_at": 1644047925,
            "handle": "supreme-pouch-44370ss18a32-sm",
            "updated_at": 1698280024,
            "published_at": 1644047925,
            "tags": [
                "consignment",
            ],
            "images": [
                {
                    "alt": "SUPREME POUCH",
                    "src": "https://cdn.shopify.com/s/files/1/0588/3677/9194/products/ss18_supreme_tnf_pouch_blk_2-l_5fb1316e-22f7-4702-9953-57f3fbdda5be.jpg?v=1644047927",
                    "width": 800,
                    "height": 534,
                    "variant_ids": []
                }
            ],
            "metafields": {
                "product": {
                    "alias": "SEALLINE SEE POUCH SMALL",
                    "colorway": "BLACK",
                    "styleCode": "SS18A30 BLACK",
                    "yearOfRelease": 2018,
                    "searchColor": [
                        "black"
                    ]
                }
            },
            "available": true,
            "price_range": {
                "from": 30,
                "to": 30
            }
        }
    ],
    "totalResults": 1000,
    "page": 1,
    "totalPages": 20,
    "facets": {
        "vendor": {
            "ADIDAS": 30,
            "JORDAN": 336,
            "NEW BALANCE": 15,
            "NIKE": 384,
            "REEBOK": 4,
            "SUPREME": 624,
            "VANS": 32
        }
    },
    "attributionToken": "2y10smI2dB7XZXXFJsLUELltgueq8NRdcRD3U8djkLqxQmaVMvg1lSCf2"
}

Collection Page Image Search

Browse

Search

Recommendations

Analytics

Utilities

Search API: Semantic Catalog Search

Authorization

Headers

Path Parameters

Body

Response

Browse

Search

Recommendations

Analytics

Utilities

​Authorization

​Headers

​Path Parameters

​Body

​Response

Authorization

Headers

Path Parameters

Body

Response