Search API: Catalog Image Search
Perform visual searches within your product catalog using uploaded images or base64 encoded image data.
curl --request POST \
--url https://app.uselayers.com/api/storefront/v1/search/image \
--header 'Accept: <accept>' \
--header 'Content-Type: <content-type>' \
--header 'X-Storefront-Access-Token: <x-storefront-access-token>' \
--data '{
"image_data": "<string>",
"image_id": "<string>",
"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
Token-based authentication header in the form of <YOUR_LAYERS_TOKEN>.
Headers
Body
Base64 Encoded PNG or JPEG Image Data. Required if image_id is not provided.
UUID identifier returned from the Image Upload API. Required if image_data is not provided. Using image_id is recommended for better performance and support for larger images.
Product attributes to include in the Response. By default all attributes are included in the response.
Parameters to fine-tune the search results.
Weight given to textual similarity (0-1). Must be provided together with visualWeight.
Weight given to visual similarity (0-1). Must be provided together with textualWeight.
Multiplier applied to the search results.
Minimum match score threshold (0-1) for including results.
Refer to our dedicated Filter Expressions guide to learn more about filter expressions.
Facets to be included.
If the count of each facet value should be calculated
If you want a min/max range for numeric facets such as price.
Anonymous contextual information of the session/customer.
The path of the page the user is on (e.g., /collections/all-products).
The referrer path of the previous page the user visited.
The source of the UTM tracking for the current session.
The medium of the UTM tracking (e.g., email, CPC).
The campaign associated with the UTM tracking.
The term or keyword used in UTM tracking.
The content description used in UTM tracking.
Indicates whether the user’s cart is empty.
The total value of the items in the user’s cart.
The number of items in the user’s cart.
Indicates whether the user is signed in.
The total number of orders made by the user.
The city associated with the user’s context.
The state or province associated with the user’s context.
The country associated with the user’s context.
Response
The unique identifier of the product.
The title of the product.
The HTML content describing the product.
The vendor of the product.
The type of the product.
The timestamp when the product was created.
The handle of the product.
The timestamp when the product was updated.
The timestamp when the product was published.
The tags associated with the product.
The parent product id if a child in a Combined Listing.
The role of the product if part of a Combined Listing.
The metafields of the product.
The calculated attributes of the product.
The first available variant (depending on OOS settings) or the variant matched with a filter or search query.
The ID of the variant.
The title of the variant.
The availability of the variant.
The sku of the variant.
The price of the variant.
The compare at price of the variant.
The metafields of the variant.
The sku of the variant.
The availability of the product.
The total number of results.
The current page number.
The total number of pages.
If includeFacetRanges is true then an object with keys of the facet attribute code and value is an object with min/max.
If retrieveFacetCount is true then an object with keys and values of the specified attributes.
The attribution token.
Usage Examples
Using Image ID (Recommended)
First, upload an image to get an image_id:
curl -X POST "https://app.uselayers.com/api/storefront/v1/images/upload" \
-H "X-Storefront-Access-Token: YOUR_TOKEN" \
-F "image=@/path/to/your/image.jpg"
Then use the returned image_id for searching:
{
"image_id": "550e8400-e29b-41d4-a716-446655440000",
"pagination": {
"page": 1,
"limit": 20
}
}
Using Base64 Image Data (Legacy)
{
"image_data": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQABAAD...",
"pagination": {
"page": 1,
"limit": 20
}
}
{
"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"
}
Was this page helpful?
curl --request POST \
--url https://app.uselayers.com/api/storefront/v1/search/image \
--header 'Accept: <accept>' \
--header 'Content-Type: <content-type>' \
--header 'X-Storefront-Access-Token: <x-storefront-access-token>' \
--data '{
"image_data": "<string>",
"image_id": "<string>",
"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"
}