Implement search logic in your backend or mobile app

This guide explains how to query the Product Recommendation API to display live (instant) and full product search results without embedding the Kameleoon HTML element. Refer to the visual integration guide for the visual method. The tutorial uses the search endpoint.

Why use the API?

Use the API for mobile applications.

Depending on your needs, this approach offers multiple benefits:

Full Control: Customize the variation display to match your design and UX standards.
Better Performance: Use optimized API calls to reduce page load delays compared to script-based solutions.
Easier Debugging: Log, monitor, and debug integrations within your client codebase using standard tools.
No Third-Party Script Dependency: Use direct calls to avoid external scripts, reduce potential conflicts, and align with security policies.
SPA-Friendly: Integrate directly into single-page applications to avoid timing issues and fit into client-side routing.
Ad Blocker Resilience: Deliver experiments consistently without third-party scripts or specific HTML markers. For more details on how ad blockers affect Kameleoon, see the FAQ.

Goal

Retrieve and display product search results based on user input using either instant (typeahead) or full search modes.

Requirements

A valid Kameleoon account with a Store ID (shop_id).
- Get your shop_id from Recommendations > Settings > Store settings in the Kameleoon app. Contact your Customer Success Manager for the key if necessary.
A Device ID (did) and Session ID (sid). (Required only when using filters or algorithms that rely on historical device/user data).
- For Kameleoon Web Experimentation, get these from the following cookies:
  - KameleoonProducts_device_id → Device ID (did)
  - KameleoonProducts_session_code → Session ID (sid)
- Otherwise, generate these values manually.

Steps

1. Configure the feed for Kameleoon search

Follow the search configuration guide to configure your feed.

2. Retrieve cookies (Kameleoon Web Experimentation only)

Generate these values manually for backend implementations or environments without Kameleoon Web Experimentation. Refer to the Init endpoint for details.

function getCookie(name) {
  const match = document.cookie.match(new RegExp('(^| )' + name + '=([^;]+)'));
  if (match) return match[2];
}
const did = getCookie('KameleoonProducts_device_id');
const sid = getCookie('KameleoonProducts_session_code');

3. Make a search request

The API supports two search types:

a. Instant search (instant_search)

Use instant search for typeahead and autocomplete results as the user types. Endpoint:

GET https://api.products.kameleoon.com/search

Name	Type	Required	Description
`did`	string	True	Device ID (from cookie)
`sid`	string	True	Session ID (from cookie)
`shop_id`	string	True	Your Kameleoon store ID
`type`	string	True	`"instant_search"`
`search_query`	string	True	User’s search input
`locations`	List	False	Comma-separated list of location IDs

Example:

curl -X GET -L 'https://api.products.kameleoon.com/search' \
             -H 'Content-Type: application/json' \
             -d '{
   "did":"abc123",
   "sid":"xyz456",
   "shop_id":"demoShop",
   "type":"instant_search",
   "search_query":"decon",
}'

b. Full search (full_search)

Use full search to display detailed results with filters, categories, pagination, and sorting. Endpoint:

GET https://api.products.kameleoon.com/search

Name	Type	Required	Description
`did`	string	True	Device ID (from cookie)
`sid`	string	True	Session ID (from cookie)
`shop_id`	string	True	Your Kameleoon store ID
`type`	string	True	`"full_search"`
`search_query`	string	True	User’s search input
`locations`	List	False	Comma-separated list of location IDs
`limit`	Integer	False	Maximum number of results
`offset`	Integer	False	Offset for pagination
`extended`	Integer/Empty	False	`1` returns full product data
`sort_by`	String	False	Sort criteria: `popular`, `price`, etc.
`order`	String	False	Sort order: `asc` or `desc`
`brands`	List	False	Filter by brand list
`categories`	List	False	Filter by category list
`filters`	String	False	Escaped JSON string for product parameters
`price_min`	Integer	False	Minimum price
`price_max`	Integer	False	Maximum price
`exclude`	List	False	Product IDs to exclude

curl -X GET -L 'https://api.products.kameleoon.com/search' \
             -H 'Content-Type: application/json' \
             -d '{
   "did":"abc123",
   "sid":"xyz456",
   "shop_id":"demoShop",
   "type":"full_search",
   "search_query":"decon",
   "limit":"10",
   "extended":"1",
   "sort_by":"price",
   "order":"asc",
}'

Refer to the filtering section for filtering details.

4. Integrate the response

a. Instant search

If the request succeeds, the API returns an HTML snippet for direct page injection, alongside product and category data for custom rendering.

For mobile applications, use the JSON product and category arrays to design a native interface.

Sample Response

{
    "search_query": "decon",
    "collections": [],
    "products_total": 1,
    "products": [
        {
            "name": "VANS | SK8-HI DECON (CUTOUT)| LEAVES\/WHITE",
            "url": "\/products\/asics-tiger-gel-lyte-v-30-years-of-gel-pack?recommended_by=instant_search&recommended_code=decon",
            "category_ids": [
                "1",
                "2",
                "295508017316"
            ],
            "barcode": "VN-05-white-4",
            "vendor_code": "VA",
            "brand": "Vans",
            "leftovers": "lot",
            "rating": 5,
            "fashion_sizes": [
                "4",
                "5",
                "6",
                "7",
                "8",
                "9",
                "10"
            ],
            "fashion_feature": "adult",
            "fashion_gender": "m",
            "fashion_wear_type": "shoe",
            "fashion_original_sizes": [
                "4",
                "5",
                "6",
                "7",
                "8",
                "9",
                "10"
            ],
            "picture": "https:\/\/images.products.kameleoon.com\/resize-images\/180\/9fa630bf863db7a87fc6d5fd2a188f\/3927252.jpg",
            "categories": [
                {
                    "id": "1",
                    "url": "\/collections\/all?recommended_by=instant_search&recommended_code=decon",
                    "name": "Men",
                    "level": "1",
                    "url_handle": "\/collections\/all?recommended_by=instant_search&recommended_code=decon"
                },
                {
                    "id": "2",
                    "url": "\/collections\/all?recommended_by=instant_search&recommended_code=decon",
                    "name": "Women",
                    "level": "1",
                    "url_handle": "\/collections\/all?recommended_by=instant_search&recommended_code=decon"
                },
                {
                    "id": "295508017316",
                    "parent_id": "1",
                    "url": "\/collections\/all?recommended_by=instant_search&recommended_code=decon",
                    "name": "Men - Sneakers",
                    "level": "2",
                    "url_handle": "\/collections\/all?recommended_by=instant_search&recommended_code=decon"
                }
            ],
            "price_formatted": "$ 179",
            "price_full_formatted": "$ 179.95",
            "price": 179,
            "price_full": 179.95,
            "image_url": "https:\/\/cdn.shopify.com\/s\/files\/1\/0564\/9180\/2788\/products\/327cd936d9a9c409cd8b36987158013f_grande.jpg?v=1622707484",
            "image_url_handle": "\/s\/files\/1\/0564\/9180\/2788\/products\/327cd936d9a9c409cd8b36987158013f_grande.jpg?v=1622707484",
            "image_url_resized": {
                "120": "https:\/\/images.products.kameleoon.com\/resize-images\/120\/9fa630bf863db7a87fc6d5fd2a188f\/3927252.jpg",
                "140": "https:\/\/images.products.kameleoon.com\/resize-images\/140\/9fa630bf863db7a87fc6d5fd2a188f\/3927252.jpg",
                "160": "https:\/\/images.products.kameleoon.com\/resize-images\/160\/9fa630bf863db7a87fc6d5fd2a188f\/3927252.jpg",
                "180": "https:\/\/images.products.kameleoon.com\/resize-images\/180\/9fa630bf863db7a87fc6d5fd2a188f\/3927252.jpg",
                "200": "https:\/\/images.products.kameleoon.com\/resize-images\/200\/9fa630bf863db7a87fc6d5fd2a188f\/3927252.jpg",
                "220": "https:\/\/images.products.kameleoon.com\/resize-images\/220\/9fa630bf863db7a87fc6d5fd2a188f\/3927252.jpg",
                "310": "https:\/\/images.products.kameleoon.com\/resize-images\/310\/9fa630bf863db7a87fc6d5fd2a188f\/3927252.jpg",
                "520": "https:\/\/images.products.kameleoon.com\/resize-images\/520\/9fa630bf863db7a87fc6d5fd2a188f\/3927252.jpg",
                "original": "https:\/\/cdn.shopify.com\/s\/files\/1\/0564\/9180\/2788\/products\/327cd936d9a9c409cd8b36987158013f_grande.jpg?v=1622707484"
            },
            "url_handle": "\/products\/asics-tiger-gel-lyte-v-30-years-of-gel-pack?recommended_by=instant_search&recommended_code=decon",
            "currency": "$",
            "_id": "3927252",
            "id": "VN-05-white-4",
            "stock_quantity": 19,
            "fashion_colors": [
                "white"
            ],
            "params": [
                {
                    "key": "Size",
                    "values": [
                        "4"
                    ]
                },
                {
                    "key": "Color",
                    "values": [
                        "white"
                    ]
                }
            ],
            "group_id": "_3927252_"
        }
    ],
    "categories": [
        {
            "id": "1",
            "name": "Men",
            "url": "\/collections\/all?recommended_by=instant_search&recommended_code=decon",
            "url_handle": "\/collections\/all?recommended_by=instant_search&recommended_code=decon",
            "count": 1
        },
        {
            "id": "2",
            "name": "Women",
            "url": "\/collections\/all?recommended_by=instant_search&recommended_code=decon",
            "url_handle": "\/collections\/all?recommended_by=instant_search&recommended_code=decon",
            "count": 1
        },
        {
            "id": "295508017316",
            "name": "Men - Sneakers",
            "parent": "1",
            "url": "\/collections\/all?recommended_by=instant_search&recommended_code=decon",
            "url_handle": "\/collections\/all?recommended_by=instant_search&recommended_code=decon",
            "count": 1
        }
    ],
    "clarification": true,
    "requests_count": 1,
    "queries": [],
    "html": "<div class=\"KameleoonProducts-search-wrapper\"> <div class=\"KameleoonProducts-search-container\"> <div class=\"KameleoonProducts-search-group\"> <div class=\"KameleoonProducts-search-group-title\"> Categories <\/div> <div class=\"KameleoonProducts-search-group-description\"> <a class=\"KameleoonProducts-search-row\" data-id=\"1\" data-remote=\"true\" href=\"\/collections\/all?recommended_by=instant_search&recommended_code=decon\"><span>Men <\/span><\/a> <a class=\"KameleoonProducts-search-row\" data-id=\"2\" data-remote=\"true\" href=\"\/collections\/all?recommended_by=instant_search&recommended_code=decon\"><span>Women <\/span><\/a> <a class=\"KameleoonProducts-search-row\" data-id=\"295508017316\" data-remote=\"true\" href=\"\/collections\/all?recommended_by=instant_search&recommended_code=decon\"><span>Men - Sneakers <\/span><\/a> <\/div> <\/div> <\/div> <div class=\"KameleoonProducts-search-container\" id=\"KameleoonProducts_search_products\"> <div class=\"KameleoonProducts-search-group KameleoonProducts-search-products\"> <div class=\"KameleoonProducts-search-group-title\"> Possible item matches <\/div> <div class=\"KameleoonProducts-search-group-description\"> <a class=\"KameleoonProducts-search-product\" href=\"\/products\/asics-tiger-gel-lyte-v-30-years-of-gel-pack?recommended_by=instant_search&recommended_code=decon\"> <div class=\"KameleoonProducts-search-product__image\" style=\"background-image: url(&#39;https:\/\/cdn.shopify.com\/s\/files\/1\/0564\/9180\/2788\/products\/327cd936d9a9c409cd8b36987158013f_grande.jpg?v=1622707484&#39;)\"><\/div> <div class=\"KameleoonProducts-search-product__name\"> VANS | SK8-HI DECON (CUTOUT)| LEAVES\/WHITE <\/div> <div class=\"KameleoonProducts-search-product__price\"> $ 179.95 <\/div> <\/a> <\/div> <\/div> <\/div> <div class=\"KameleoonProducts-search-close\"><\/div><\/div>"
}

a. Full Search

Integrating full search also provides an HTML snippet for displaying results. The response also includes brands and filters arrays in addition to the categories array.

The filters array contains keys and values from the product params fields. Use these to build the filter interface.

Example full search results page:

Applying filters

The following example shows the full search request with the filters selected in the image above:

{
   "did":"abc123",
   "shop_id":"9fa630bf863db7a87fc6d5fd2a188f",
   "type":"full_search",
   "search_query":"vans",
   "input_query":"vans",
   "categories":"295508017316",
   "filters":{"Color":["white"],"Size":["4"]},
   "brands":"vans"

}

Sample response

{
    "search_query": "decon",
    "collections": [],
    "products_total": 1,
    "products": [
        {
            "name": "VANS | SK8-HI DECON (CUTOUT)| LEAVES\/WHITE",
            "url": "\/products\/asics-tiger-gel-lyte-v-30-years-of-gel-pack?recommended_by=full_search&recommended_code=decon",
            "category_ids": [
                "1",
                "2",
                "295508017316"
            ],
            "barcode": "VN-05-white-4",
            "vendor_code": "VA",
            "brand": "Vans",
            "leftovers": "lot",
            "rating": 5,
            "fashion_sizes": [
                "4",
                "5",
                "6",
                "7",
                "8",
                "9",
                "10"
            ],
            "fashion_feature": "adult",
            "fashion_gender": "m",
            "fashion_wear_type": "shoe",
            "fashion_original_sizes": [
                "4",
                "5",
                "6",
                "7",
                "8",
                "9",
                "10"
            ],
            "picture": "https:\/\/images.products.kameleoon.com\/resize-images\/180\/9fa630bf863db7a87fc6d5fd2a188f\/3927252.jpg",
            "categories": [
                {
                    "id": "1",
                    "url": "\/collections\/all?recommended_by=full_search&recommended_code=decon",
                    "name": "Men",
                    "level": "1",
                    "url_handle": "\/collections\/all?recommended_by=full_search&recommended_code=decon"
                },
                {
                    "id": "2",
                    "url": "\/collections\/all?recommended_by=full_search&recommended_code=decon",
                    "name": "Women",
                    "level": "1",
                    "url_handle": "\/collections\/all?recommended_by=full_search&recommended_code=decon"
                },
                {
                    "id": "295508017316",
                    "parent_id": "1",
                    "url": "\/collections\/all?recommended_by=full_search&recommended_code=decon",
                    "name": "Men - Sneakers",
                    "level": "2",
                    "url_handle": "\/collections\/all?recommended_by=full_search&recommended_code=decon"
                }
            ],
            "price_formatted": "$ 179",
            "price_full_formatted": "$ 179.95",
            "price": 179,
            "price_full": 179.95,
            "image_url": "https:\/\/cdn.shopify.com\/s\/files\/1\/0564\/9180\/2788\/products\/327cd936d9a9c409cd8b36987158013f_grande.jpg?v=1622707484",
            "image_url_handle": "\/s\/files\/1\/0564\/9180\/2788\/products\/327cd936d9a9c409cd8b36987158013f_grande.jpg?v=1622707484",
            "image_url_resized": {
                "120": "https:\/\/images.products.kameleoon.com\/resize-images\/120\/9fa630bf863db7a87fc6d5fd2a188f\/3927252.jpg",
                "140": "https:\/\/images.products.kameleoon.com\/resize-images\/140\/9fa630bf863db7a87fc6d5fd2a188f\/3927252.jpg",
                "160": "https:\/\/images.products.kameleoon.com\/resize-images\/160\/9fa630bf863db7a87fc6d5fd2a188f\/3927252.jpg",
                "180": "https:\/\/images.products.kameleoon.com\/resize-images\/180\/9fa630bf863db7a87fc6d5fd2a188f\/3927252.jpg",
                "200": "https:\/\/images.products.kameleoon.com\/resize-images\/200\/9fa630bf863db7a87fc6d5fd2a188f\/3927252.jpg",
                "220": "https:\/\/images.products.kameleoon.com\/resize-images\/220\/9fa630bf863db7a87fc6d5fd2a188f\/3927252.jpg",
                "310": "https:\/\/images.products.kameleoon.com\/resize-images\/310\/9fa630bf863db7a87fc6d5fd2a188f\/3927252.jpg",
                "520": "https:\/\/images.products.kameleoon.com\/resize-images\/520\/9fa630bf863db7a87fc6d5fd2a188f\/3927252.jpg",
                "original": "https:\/\/cdn.shopify.com\/s\/files\/1\/0564\/9180\/2788\/products\/327cd936d9a9c409cd8b36987158013f_grande.jpg?v=1622707484"
            },
            "url_handle": "\/products\/asics-tiger-gel-lyte-v-30-years-of-gel-pack?recommended_by=full_search&recommended_code=decon",
            "currency": "$",
            "_id": "3927252",
            "id": "VN-05-white-4",
            "stock_quantity": 19,
            "fashion_colors": [
                "white"
            ],
            "params": [
                {
                    "key": "Size",
                    "values": [
                        "4"
                    ]
                },
                {
                    "key": "Color",
                    "values": [
                        "white"
                    ]
                }
            ],
            "group_id": "_3927252_"
        }
    ],
    "price_range": {
        "min": 179.95000000000002,
        "max": 179.95000000000002
    },
    "price_ranges": [
        {
            "from": 10,
            "count": 1
        }
    ],
    "price_median": 0,
    "filters": {
        "Color": {
            "count": 1,
            "values": {
                "white": 1
            }
        },
        "Size": {
            "count": 1,
            "values": {
                "4": 1
            },
            "ranges": {
                "min": "4",
                "max": "4"
            }
        }
    },
    "brands": [
        {
            "name": "Vans",
            "count": 1
        }
    ],
    "categories": [
        {
            "id": "1",
            "name": "Men",
            "url": "\/collections\/all?recommended_by=full_search&recommended_code=decon",
            "url_handle": "\/collections\/all?recommended_by=full_search&recommended_code=decon",
            "count": 1
        },
        {
            "id": "2",
            "name": "Women",
            "url": "\/collections\/all?recommended_by=full_search&recommended_code=decon",
            "url_handle": "\/collections\/all?recommended_by=full_search&recommended_code=decon",
            "count": 1
        },
        {
            "id": "295508017316",
            "name": "Men - Sneakers",
            "parent": "1",
            "url": "\/collections\/all?recommended_by=full_search&recommended_code=decon",
            "url_handle": "\/collections\/all?recommended_by=full_search&recommended_code=decon",
            "count": 1
        }
    ],
    "industrial_filters": {
        "fashion_sizes": [
            {
                "size": 4,
                "count": 1
            },
            {
                "size": 5,
                "count": 1
            },
            {
                "size": 6,
                "count": 1
            },
            {
                "size": 7,
                "count": 1
            },
            {
                "size": 8,
                "count": 1
            },
            {
                "size": 9,
                "count": 1
            },
            {
                "size": 10,
                "count": 1
            }
        ],
        "colors": [
            {
                "color": "white",
                "count": 1
            }
        ]
    },
    "clarification": true,
    "requests_count": 1,
    "html": "<div class=\"KameleoonProducts-search-items\"> <div class=\"KameleoonProducts-search-item\"> <div class=\"KameleoonProducts-search-item-photo\"> <a href=\"\/products\/asics-tiger-gel-lyte-v-30-years-of-gel-pack?recommended_by=full_search&recommended_code=decon\"><img class=\"item_img\" src=\"https:\/\/cdn.shopify.com\/s\/files\/1\/0564\/9180\/2788\/products\/327cd936d9a9c409cd8b36987158013f_grande.jpg?v=1622707484\" \/><\/a> <\/div> <div class=\"KameleoonProducts-search-item-title\"> <a href=\"\/products\/asics-tiger-gel-lyte-v-30-years-of-gel-pack?recommended_by=full_search&recommended_code=decon\">VANS | SK8-HI DECON (CUTOUT)| ...<\/a> <\/div> <div class=\"KameleoonProducts-search-item-price\"> $ 179.95 <\/div> <\/div> <\/div>"
}

Notes

Ensure cookies are accessible before making requests.
Use full search with extended=1 for detailed product listings, such as on product pages.
Customize the returned HTML or render a custom UI using the JSON response. se.

APIs

Documentation Index

​Why use the API?

​Goal

​Requirements

​Steps

​1. Configure the feed for Kameleoon search

​2. Retrieve cookies (Kameleoon Web Experimentation only)

​3. Make a search request

​a. Instant search (instant_search)

​b. Full search (full_search)

​4. Integrate the response

​a. Instant search

Sample Response

​a. Full Search

​Applying filters

Sample response

​Notes

Why use the API?

Goal

Requirements

Steps

1. Configure the feed for Kameleoon search

2. Retrieve cookies (Kameleoon Web Experimentation only)

3. Make a search request

a. Instant search (instant_search)

b. Full search (full_search)

4. Integrate the response

a. Instant search

a. Full Search

Applying filters

Notes