Skip to main content

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?

caution

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_idDevice ID (did)
      • KameleoonProducts_session_codeSession ID (sid)
    • If not, you will need to generate these values yourself.

Steps

You can check how to configure your feed in this guide.

2. Retrieve required cookies (only with Kameleoon Web Experimentaton)

caution

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:

Used for typeahead/autocomplete search while the user is typing.

Endpoint:

GET https://api.products.kameleoon.com/search
NameTypeRequiredDescription
didstringTrueDevice ID (from cookie)
sidstringTrueSession ID (from cookie)
shop_idstringTrueYour Kameleoon store ID
typestringTrue"instant_search"
search_querystringTrueUser's search input
locationsListfalseA 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",
}'

Used for displaying detailed search results with filters, categories, pagination, and sorting.

Endpoint:

GET https://api.products.kameleoon.com/search
NameTypeRequiredDescription
didstringTrueDevice ID (from cookie)
sidstringTrueSession ID (from cookie)
shop_idstringTrueYour Kameleoon store ID
typestringTrue"full_search"
search_querystringTrueUser's search input
locationsListfalseA comma-separated list of locations IDs.
limitintfalseMax number of results
offsetintfalseOffset for pagination
extendedint or emptyfalse1 to return full product data
sort_bystringfalseSort by: popular, price, discount, etc.
orderstringfalseSort order: asc or desc
brandslistfalseFilter by brand list
categorieslistfalseFilter by category list
filtersstringfalseEscaped JSON string for product params
price_minintfalseMinimum price
price_maxintfalseMaximum price
excludelistfalseProduct 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

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(&#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>"
}

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.

note

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.