> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kameleoon.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Kameleoon.API.Products: Recommendations and search

> Reference for the Kameleoon.API.Products methods that retrieve recommended products, search results, product interactions, product data, and recommended collections.

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

> [!NOTE]
>
> 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](https://docs.kameleoon.com/developer-docs/apis/activation-api-js/api-reference/modules/products-tracking.md).

## obtainRecommendedProducts

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

```javascript theme={null}
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
  }
);
```

> [!WARNING]
>
> 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.](#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.

```javascript theme={null}
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.

```javascript theme={null}
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()`.

```javascript theme={null}
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()`.

```javascript theme={null}
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](https://docs.kameleoon.com/developer-docs/apis/activation-api-js/api-reference/objects/goal-segment-trigger-and-product.md#product). This field receives the same object that `trackProductView` sends. |

## obtainRecommendedCollections

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

```javascript theme={null}
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 |