Implementing the search logic in your back-end and / or your mobile apps
This guide explains an alternative method for querying Kameleoon’s Product Recommmendation API to display live (instant) and full product search results, instead of embedding the Kameleoon HTML element. See this guide if you prefer the visual integration method.
We will be using the search endpoint.
Why Use the API?
API usage is mandatory for mobile applications;
Depending on your needs this approach offers multiple benefits:
- Full Control: Clients can fully customize how and where variants are displayed, matching their design and UX standards.
- Better Performance: API calls can be optimized for performance, reducing page load delays compared to script-based solutions.
- Easier Debugging: Integration within the client’s own codebase allows better logging, monitoring, and debugging using familiar tools.
- No Third-Party Script Dependency: Avoids loading external scripts, reducing potential conflicts and aligning with security/performance policies.
- SPA-Friendly: Ideal for single-page applications, where direct API calls avoid timing issues and fit naturally into client-side routing.
- Ad Blocker Resilience: Since there's no reliance on third-party scripts or specific HTML markers, this method is less likely to be blocked by ad blockers, ensuring consistent experiment delivery. For more details on how ad blockers affect Kameleoon see this 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
)shop_id
can be found in Recommendations > Settings > Store settings in the Kameleoon app. You can also contact your Customer Success Manager for the key.
-
A Device ID (
did
) and Session ID (sid
):- If you are using Kameleoon Web Experimentaton, you can retrieve these from the following cookies:
KameleoonProducts_device_id
→ Device ID (did
)KameleoonProducts_session_code
→ Session ID (sid
)
- If not, you will need to generate these values yourself.
- If you are using Kameleoon Web Experimentaton, you can retrieve these from the following cookies:
Steps
1. Configure the feed for Kameleoon search
You can check how to configure your feed in this guide.
2. Retrieve required cookies (only with Kameleoon Web Experimentaton)
If you are not using Kameleoon Web Experimentaton you will need to generate these values yourself.
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
)
Used for typeahead/autocomplete search while the user is typing.
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 | A comma-separated list of locations IDs. |
Exemple:
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
)
Used for displaying detailed search 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 | A comma-separated list of locations IDs. |
limit | int | false | Max number of results |
offset | int | false | Offset for pagination |
extended | int or empty | false | 1 to return full product data |
sort_by | string | false | Sort by: popular , price , discount , 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 params |
price_min | int | false | Minimum price |
price_max | int | 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",
}'
You can go to this section to learn how to filter results.
4. Integrate the response
a. Instant Search
You’ll receive an HTML snippet you can directly inject into your page, along with product/category data for custom rendering if needed.
For mobile apps, use the JSON products and categories 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('https:\/\/cdn.shopify.com\/s\/files\/1\/0564\/9180\/2788\/products\/327cd936d9a9c409cd8b36987158013f_grande.jpg?v=1622707484')\"><\/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
To integrate a full search, we also provide an HTML snippet to help you display the results.
In addition to the categories
array, the response also includes brands
and filters
arrays.
The filters
array contains all available keys and their corresponding values from the params
fields of the product objects.
These are intended to be used to build your filter UI. See the example below.
Example full search results page:
Applying filters
Here is the full search request with the filters selected on the picture 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
- Always ensure cookies are accessible before making the request.
- Use full search with
extended=1
for detailed product listings (e.g., product pages). - Customize the returned HTML from the API or render your own UI based on the JSON.