Kameleoon.API.Products: Recommendations and search

Use these methods to retrieve recommended products, search results, product interactions, product data, and recommended collections.

This module is available when subscribed to the Product Recommendation module or Product Targeting add-on.

Recommendations need correct product tracking to return meaningful results. See Kameleoon.API.Products: Tracking.

obtainRecommendedProducts

The obtainRecommendedProducts() method retrieves recommended products computed by the specified algorithm through an asynchronous server call.

Kameleoon.API.Products.obtainRecommendedProducts(
  "1a2b3c4d",
  {
    item: 123500,
    exclude: [3, 14, 159, 26535],
    category: 146,
    search_query: "To be or not to be",
    limit: 15,
    brands: ["Alas", "poor", "Yorick", 'kameleooner'],
    categories: [1, 146, 123500]
  },
  function (response) {
    // the functionality of rendering a block of product recommendations
  },
  function (error) {
    // when something went wrong
  }
);

This method requires correct product tracking, such as trackProductView() or trackCategoryView(), to return meaningful results.

Arguments

Name	Type	Description
code	String	Unique code of the recommendation block.
params	Object	Parameters to control the data returned by the recommendation platform.
successCallback	Function	Callback function receiving the API response object. This field is mandatory.
errorCallback	Function	Callback function executing if an error occurs. This field is optional.

Parameters to control the data returned by the recommendation platform

Name	Type	Description
item	String	ID of the current product. Mandatory for “Similar” and “They also bought this product” algorithms.
exclude	Array	Comma-separated list of product identifiers for exclusion.
extended	Number	When `1`, the method returns full product details. If omitted, it returns only product IDs.
category	Number	Mandatory for algorithms on category pages. Limits recommendations to the specified category.
categories	Array	This field is optional. If used, it returns recommended products only from the specified categories (a comma-separated list of category IDs).
brands	Array	This field is optional. If used, it returns recommended products only from specified brands (a comma-separated list of brands).
locations	Array	This field is optional. If used, it returns recommended products available in the listed locations (a comma-separated list of location IDs).
limit	Number	This field is optional. Maximum number of recommended products.
exclude_brands	Number	This field is optional. A comma-separated list of brands to exclude from the recommendation.

API response The callback function receives the API response object with the following values.

Name	Type	Description
html	String	The block HTML code. Customize the HTML template in the Kameleoon personal account.
title	String	The block title. Corresponds to the value of the “Action” element in the block rules.
products	Array	A list of product IDs.
id	Number	Unique block identifier. Corresponds to the block ID in the list of blocks in the Kameleoon personal account

obtainInstantSearchProducts

The obtainInstantSearchProducts() method retrieves personalized instant search results from Kameleoon Search through an asynchronous server call.

Kameleoon.API.Products.obtainInstantSearchProducts(
 {
  search_query: "To be or not to be"
 },
 function (response) {
  // the functionality to render a block from instant search
 },
 function (error) {
  // to handle when something goes wrong
 }
);

Arguments

Name	Type	Description
search_query	String	User-provided search query. This field is mandatory.
successCallback	Function	Callback function receiving the API response object. This field is mandatory.
errorCallback	Function	Callback function executing if an error occurs. This field is optional.

API response The callback function receives the API response object with the following values. In the table, [] marks an array of objects, so products[].name is the name of each product.

Name	Type	Description
search_query	String	Search query.
categories	Array	Array with information about categories.
categories[].id	String	Category ID.
categories[].name	String	Category name.
categories[].url	String	Category URL.
categories[].count	Number	Count of products in the category.
filters	Array	Array with information about filters.
filters[].filter.count	Number	Total count of products with these parameters.
filters[].filter.values[].value	String	Value label.
filters[].filter.values[].count	Number	Count of products with this parameter.
html	String	HTML code of the block with products. You customize the template in the Kameleoon personal account.
price_range	Object	Minimum and maximum price of products.
price_range.min	Number	Minimum price.
price_range.max	Number	Maximum price.
products	Array	Array with information about products.
products[].description	String	Product description.
products[].url	String	Absolute product URL.
products[].url_handle	String	Relative product URL.
products[].picture	String	Product picture URL in the Kameleoon storage.
products[].name	String	Product name.
products[].price	Number / int	Product price.
products[].price_full	Number / float	Product price.
products[].price_formatted	String	Product price with currency.
products[].price_full_formatted	String	Product price with currency.
products[].image_url	String	Absolute product picture URL in the Kameleoon storage.
products[].image_url_handle	String	Relative product picture URL in the Kameleoon storage.
products[].image_url_resized	Array	Product image resize URLs.
products[].currency	String	Product currency. Corresponds to the currency of the personal account in Kameleoon, or a custom value specified in the shop settings in the personal account.
products[].id	String	Product ID.
products[].old_price	Number / int	Product old price. Default is 0.
products[].old_price_full	Number / float	Product old price.
products[].old_price_formatted	String	Product old price with currency.
products[].old_price_full_formatted	String	Product old price with currency.
products[].categories	Array	Product categories. Included only when the request passes the `extended` parameter.
products[].categories[].id	String	Category ID.
products[].categories[].name	String	Category name.
products[].categories[].parent_id	String	Parent category ID.
products[].categories[].url	String	Category URL.
products[].categories[].category_ids	Array	Product category IDs.
search_query_redirects	Array	Array with information about redirects.
search_query_redirects[].query	String	Search query.
search_query_redirects[].redirect_link	String	URL for the redirect.
search_query_redirects[].deep_link	String	URL for mobile apps.
products_total	Number	Total number of products.

obtainFullSearchProducts

Use the obtainFullSearchProducts() method to retrieve full search results from the Kameleoon Search solution with filtering options.

Kameleoon.API.Products.obtainFullSearchProducts(
 {
  search_query: "To be or not to be",
  limit: 15,
  brands: ["Alas", "poor", "Yorick"],
  categories: [1, 146, 100500],
  filters: { key: ["value"], key: ["value"] },
  sort_by: "price",
  order: "asc"
 },
 function (response) {
  // the functionality to render a block from full search
 },
 function (error) {
  // when something went wrong
 }
);

Arguments

Name	Type	Description
search_query	Object	User-provided search query and optional filter parameters. Review the filtering parameters in the next section. This field is mandatory.
successCallback	Function	Callback function receiving the API response object. This field is mandatory.
errorCallback	Function	Callback function executing if an error occurs. This field is optional.

Parameters to filter results

Name	Type	Description
search_query	String	Search query. This field is mandatory.
limit	Number	Limit of results. This field is optional.
offset	Number	Offset of results. This field is optional.
category_limit	Number	How many categories for sidebar filter to return. This field is optional.
categories	Array	Comma separated list of categories to filter. This field is optional.
extended	Number	Set to `true` for full search results.
sort_by	String	Sort by parameter: `popular`, `price`, `discount`, `sales_rate`, `date`. This field is optional.
order	String	Sort direction: asc or desc (default). This field is optional.
locations	Array	Comma separated list of locations IDs. This field is optional.
brands	Array	Comma separated list of brands to filter. This field is optional.
filters	String	Optional escaped JSON string with filter parameters. For example: `{"bluetooth":["yes"],"offers":["15% cashback"],"weight":["1.6"]}`. This field is optional.
price_min	Number	Min price. This field is optional.
price_max	Number	Max price. This field is optional.
colors false	Array	Comma separated list of colors. This field is optional.
fashion_sizes	Array	Comma separated list of sizes. This field is optional.
exclude	Array	Comma separated list of products IDs to exclude from search results. This field is optional.
email	String	It’s only for S2S integration, when service doesn’t have user’s session. Mobile SDK doesn’t use it. This field is optional.
no_clarification	Boolean	Disables clarified search. Defaults to false. Don’t use this parameter unless Kameleoon support instructs you to.
merchants	Array	Comma separated list of merchants. This field is optional.
filters_search_by	String	Available options for filter: `name`, `quantity`, `popularity`. This field is optional.

API response The callback function receives the API response object with the following values. In the table, [] marks an array of objects, so products[].name is the name of each product.

Name	Type	Description
search_query	String	Search query typed by the user.
brands	Array	Array with information about brands.
brands[].name	String	Brand name.
brands[].picture	String	Brand picture.
categories	Array	Array with information about categories.
categories[].alias	String	Category alias.
categories[].id	String	Category ID.
categories[].name	String	Category name.
categories[].parent	String	Parent category ID.
categories[].url	String	Category URL.
filters	Array	Array with information about filters.
filters[].filter.count	Number	Total count of products with these parameters.
filters[].filter.values[].value	String	Value label.
filters[].filter.values[].count	Number	Count of products with this parameter.
html	String	HTML code of the block with products. You customize the template in the Kameleoon personal account.
price_range	Object	Minimum and maximum price of products.
price_range.min	Number	Minimum price.
price_range.max	Number	Maximum price.
products	Array	Array with information about products.
products[].brand	String	Product brand.
products[].currency	String	Product currency. Corresponds to the currency of the personal account in Kameleoon, or a custom value specified in the shop settings in the personal account.
products[].id	String	Product ID.
products[].is_new	Boolean	Product property. Default is null.
products[].name	String	Product name.
products[].old_price	String	Product old price. Default is 0.
products[].picture	String	Product picture URL in the Kameleoon storage.
products[].price	Number	Product price.
products[].price_formatted	String	Product price with currency.
products[].url	String	Product URL.
products[].barcode	String	Product barcode. Included only when the request passes the `extended` parameter.
products[].categories	Array	Product categories.
products[].categories[].id	String	Category ID.
products[].categories[].name	String	Category name.
products[].categories[].parent	String	Parent category ID.
products[].params	Array	Information about product parameters.
products[].params[].key	String	Parameter name.
products[].params[].values	Array	Parameter values.
products_total	Number	Total count of products.

obtainProductInteractions

The obtainProductInteractions() method retrieves interaction metrics for products tracked via trackProductView(), trackTransaction(), or trackAddToCart().

Kameleoon.API.Products.obtainProductInteractions("123456", product => {
  console.log("product", product); // {123456: {views: 1, cartQuantities: 0, boughtQuantities: 0}}
});
Kameleoon.API.Products.obtainProductInteractions(["123456", "654321"], products => {
  console.log("products", products);
});
Kameleoon.API.Products.obtainProductInteractions(
  "123456",
  callback,
  new Date().getTime() - 1000 * 60 * 60 * 24, // timeBegin
  new Date().getTime() // timeEnd
);

Arguments

Name	Type	Description
eans	Array	Product IDs (as Strings). This field is mandatory.
callback	Function	Callback function receiving the product data. This field is mandatory.
timeBegin	Number	Start of the date range (UNIX milliseconds timestamp).
timeEnd	Number	End of the date range (UNIX milliseconds timestamp).

API response

Name	Type	Description
eans	Array	Unique identifier of the product. Each product ID maps to an object containing interaction metrics.
views	integer	Number of times visitors viewed the product.
cartQuantities	integer	Total number of times visitors added the product to their carts.
boughtQuantities	integer	Total number of times visitors purchased the product.

obtainProductData

The obtainProductData() method retrieves product information for items sent via trackProductView().

Kameleoon.API.Products.obtainProductData("123456", product => {
  console.log("product", product);
});
Kameleoon.API.Products.obtainProductData(["123456", "654321"], products => {
  console.log("products", products);
});
Kameleoon.API.Products.obtainProductData("123456", callback, {
  name: true,
  categoryId: true
}); // {123456: {name: '', categoryId: '' }}

Arguments

Name	Type	Description
eans	Array	Product IDs (as Strings). This field is mandatory.
callback	Function	Callback function receiving the product data. This field is mandatory.
parameters	Object	Optional parameters to retrieve specific fields. Defaults to `{ all: true }`.

API response

Name	Type	Description
eans	Array	Unique identifier of the product. Each product ID maps to an object containing interaction metrics.
productData	Object	Product object. This field receives the same object that `trackProductView` sends.

obtainRecommendedCollections

The obtainRecommendedCollections() method retrieves products from the specified collection.

Kameleoon.API.Products.obtainRecommendedCollections("123456", collections => {
    /* The functionality of rendering a product collection block */
    console.log("collections", collections);
}, error => {
    /* Error handling logic if something goes wrong */
});

Arguments

Name	Type	Description
collectionId	String	Product collection ID, available in the Product Collections dashboard section.
successCallback	Function	Callback function receiving the API response object. This field is mandatory.
errorCallback	Function	Callback function executing if an error occurs. This field is optional.

API response Products API returns an array of objects. Each object in the products array contains the following:

Parameter	Type	Description
name	String	Name of the product
url	String (URL)	URL of the product page
description	String	Description of the product
category_ids	Array of Strings	List of category IDs the product belongs to
brand	String	Brand of the product
fashion_feature	String	Fashion feature (for example, `"adult"`)
fashion_gender	String	Intended gender for the product
sales_rate	Integer	Product’s sales rate
relative_sales_rate	Float	Sales rate relative to other products
picture	String (URL)	URL of the main product image
categories	Array of Objects	List of category objects (system-defined structure)
price_formatted	String	Formatted product price (for example, `$29.99`)
price_full_formatted	String	Formatted full/original price
price	Float	Current product price
price_full	Float	Original/full price before any discounts
image_url	String (URL)	URL of the resized product image
image_url_handle	String (URL)	Processed image URL (handle-based)
image_url_resized	String (URL)	Resized image URL
url_handle	String	URL handle used to access the product within the collection
currency	String	Currency code used for the product price (for example, `USD`, `EUR`)
id	String	Product ID (numeric or string depending on system)
html	String (HTML)	The HTML template selected when you created the collection

APIs

​obtainRecommendedProducts

​Parameters to control the data returned by the recommendation platform

​obtainInstantSearchProducts

​obtainFullSearchProducts

​Parameters to filter results

​obtainProductInteractions

​obtainProductData

​obtainRecommendedCollections

obtainRecommendedProducts

Parameters to control the data returned by the recommendation platform

obtainInstantSearchProducts

obtainFullSearchProducts

Parameters to filter results

obtainProductInteractions

obtainProductData

obtainRecommendedCollections