Skip to main content

Recommendations API reference

For an introduction to retrieving recommendation data generated from recommendation strategies, see Retrieving recommendation data for strategies.

Learn how to make Recommendations API requests to retrieve recommendation data for strategies.

tip

You can also retrieve recommendation data for strategies using the frosmo.easy.strategies.fetch() JavaScript function. The function supports all algorithms. For more information, see Retrieving recommendation data for strategies.

Requests

URL

The URL for Recommendations API requests is https://<platform_instance>/recoApi/v2, where <platform_instance> is the domain name of your Frosmo Platform instance.

To get the URL for your Frosmo Platform instance:

  1. Log in to the Frosmo Control Panel, and select your site.

  2. In the header, click your username, and select API Access.

  3. In the Recommendations API section, copy the URL.

    URL for Recommendations API requests

Authentication

The Recommendations API does not require authentication.

Methods

The Recommendations API supports the GET HTTP method for recommendation strategies.

Syntax

To retrieve recommendation data for a recommendation strategy, make the following GET request:

GET https://<platform_instance>/recoApi/v2?method=strategy&
origin=<site_origin>&
strategy=<strategy_id>&
context={<strategy_context>}

Parameters

Query parameters for Recommendations API requests (strategies)
ParameterDescriptionTypeRoleExample

method

Request type.

Use the value strategy.

String

Required

method=strategy

origin

Site origin.

To find out your site's origin, see Getting your site origin.

String

Required

origin=shop_company_com

strategy

Recommendation strategy ID.

String

Required

strategy=product-page--recommended-for-you

cookieId

Frosmo ID of the visitor who sees the recommendation returned by the API request.

This parameter is required in the following cases:

  • The strategy requires a user context for generating the recommendation data.

  • The strategy sorts the recommendation data by visitor affinity.

The strategy requires a user context if it uses any of the following algorithms:

  • Bought together with categories recently bought by the visitor

  • Bought together with items recently viewed by the visitor

  • Most viewed by the visitor

  • Recently viewed by the visitor

  • Viewed together with categories recently viewed by the visitor

  • Viewed together with items recently viewed by the visitor

The ID allows the platform to use the visitor's user context and affinity profile for personalizing the recommendation for the visitor.

To get the ID, see Getting a visitor's Frosmo ID.

String

Optional

cookieId=dsr77t.kstzihlx

context

Contextual information about the page where the API request is made.

The information allows the API to return the correct recommendation data for the page. The exact information required depends on the page type of the recommendation strategy: the information must match the page type.

The value is a JSON object.

note

If the page type of the recommendation strategy is Other, this parameter is not required. You can either pass an empty context or omit this parameter from the API request.

Recommendation strategy context object

Required

# Product page context

context={
"page": {
"product": {
"id": "719",
"category": "Books/Fiction/Fantasy"
}
}
}

variants

Define whether to also return the data for product variants.

If a recommended product has one or more variants, the API returns the full product data for each variant in the variants array property of the recommended item object.

The possible values are:

  • false: Do not return product variant data.

  • true: Return product variant data.

The default value is false.

Boolean

Optional

variants=true

profile

Define the visitor's profiling choice if the site uses selective profiling. The choice determines whether the API returns recommendation data that is personalized for the visitor.

The possible values are:

  • opt-in: The visitor has opted in to seeing personalized, targeted content.

  • opt-out: The visitor has opted out of seeing personalized, targeted content.

  • Empty: The visitor has not made their profiling choice.

The default value is empty.

Each visitor's profiling choice is stored in their context. You can get the choice using the frosmo.easy.profile.get() function.

note

You must always define this parameter on a site that uses selective profiling.

Never define this parameter on a site that does not use selective profiling.

How the profiling choice works

If you set the value to opt-in or empty, the API returns the recommendation data normally.

If you set the value to opt-out:

  • The API does not apply any visitor affinity to the recommendation. If the strategy is configured to sort the recommendation data by affinity, the API instead returns the data sorted in descending order of rank as determined by the algorithms. The more highly an algorithm recommends an item, the higher the rank that the algorithm assigns to the item.

  • The API does not return recommendation data from algorithms that generate personalized results (such as a "by the visitor" algorithm).

Depending on the strategy settings, the API therefore either returns a non-personalized version of the recommendation or a recommendation with the personalized results removed.

String

Optional

profile=opt-out

shuffle

warning

This property is deprecated. If you want to shuffle the order of items, use the corresponding sorting setting in the strategy.

Define whether to randomly shuffle the order of items in the recommendation data.

The possible values are:

The default value is false.

Boolean

Optional

shuffle=true

debug

Define whether to return debugging information about the recommendation.

warning

Use the debugging information only for development and testing purposes. Do not use the information in production, since Frosmo does not guarantee that the information structure and content will remain the same.

The debugging information consists of:

  • Selected details about the recommendation strategy that was used to generate the recommendation

  • Raw recommendation data (dataPoints) that was used to build the final recommendation data

  • For a product recommendation: Product API debugging information for the recommended products

The possible values are:

  • false: Do not return debugging information.

  • true: Return debugging information.

The default value is false.

Boolean

Optional

debug=true

Recommendation strategy context object

The following table describes the context object for recommendation strategies. The object provides information about the context into which the recommendation data is retrieved.

note

If the page type of the recommendation strategy is Other, the context object is not required. You can either define an empty context object or omit the object from the API request.

Recommendation strategy context object properties
PropertyDescriptionTypeRoleExample

page

Context information about the current page.

Page context object

Required

# Page context object for a product page

"page": {
"product": {
"id": "719",
"category": "Books/Fiction/Fantasy"
}
}

Page context object

The following table describes the page object of the recommendation strategy context object. The page object provides context information about the current page.

note

The page context must match the page type of the recommendation strategy. The only exception is the page type Other, which does not require a page context.

Page context object properties
PropertyDescriptionTypeRoleExample

brand

Context information about the current brand page.

Brand page context object

Optional

"brand": {
"name": "Wakita"
}

cart

Context information about the current shopping cart page.

Cart page context object

Optional

"cart": {
"ids": [
"958",
"175",
"280"
]
}

category

Context information about the current category page.

Category page context object

Optional

"category": {
"name": "Books/Fiction/Fantasy",
"categories": [
"Books/Fiction/Fantasy",
"Books/Fiction/Speculative"
]
}

product

Context information about the current product page.

info

Here, "product" refers to any item that a site sells or offers to visitors, or that the site otherwise tracks for conversions or transactions. A product can be, for example, a retail product, a blog article, an online game, a magazine subscription, or a downloadable brochure.

Product page context object

Optional

"product": {
"id": "719",
"category": "Books/Fiction/Fantasy"
}

search

Context information about the current search page.

Search page context object

Optional

"search": {
"ids": [
"958",
"655",
"358",
"809",
"955"
],
"categories": [
"Books/Fiction/Fantasy",
"Books/Fiction/Speculative"
"Books/Fiction/Scifi"
]
}

Brand page context object

The following table describes the brand object of the page context object. The brand object provides context information about the current brand page.

Brand page context object properties
PropertyDescriptionTypeRoleExample

name

Name of the brand.

String

Required

"name": "Wakita"

Cart page context object

The following table describes the cart object of the page context object. The cart object provides context information about the current shopping cart page.

Cart page context object properties
PropertyDescriptionTypeRoleExample

ids

IDs of the items currently in the visitor's shopping cart.

You can define a maximum of 20 IDs. You must define at least one ID.

The IDs are relevant for strategies that use the Bought together with items in the cart algorithm. The IDs are the target items against which the platform generates the recommendation.

The platform matches the IDs against the id attribute value tracked for an item.

note

You're free to choose the logic by which you select the IDs, especially if a visitor's shopping cart contains more than 20 items.

Array of strings

Required

"ids": [
"357",
"958",
"990"
]

Category page context object

The following table describes the category object of the page context object. The category object provides context information about the current category page.

Category page context object properties
PropertyDescriptionTypeRoleExample

categories

Names of the categories whose items are shown on the current category page.

The category names are relevant for strategies that use the Bought together with current category or Viewed together with current category algorithm, or that have the Only return items filter option selected. The platform generates the recommendation against the listed categories.

The platform matches the category names against the categories (array of strings) or type (string) attribute value tracked for an item, depending on which attribute the site uses for storing category information.

tip

You can also use partial category names, since the API checks whether the category names in the database start with the strings you provide here.

For example:

  • "Music" matches Music, Musical Instruments, and any other category name that starts with "Music".

  • "Books/Fiction" matches Books/Fiction/Fantasy, Books/Fiction/Speculative, and any other category name that starts with "Books/Fiction".

Examples
  • If the Furnishing category page shows items from the Blankets, Curtains, and Rugs categories, list those three category names here.

  • If the Books/Fiction category pfrom theage shows items iction/Fantasy, Books/Fiction/Speculative, and Books/Kids/Fiction` categories, list those three category names here.

  • Books/ If thecategory page instead only shows items from categories starting with "Books/Fiction", simply list Books/Fiction` here.

Array of strings

Required

"categories": [
"Books/Fiction/Fantasy",
"Books/Fiction/Speculative",
"Books/Kids/Fiction"
]

Product page context object

The following table describes the product object of the page context object. The product object provides context information about the current product page.

Product page context object properties
PropertyDescriptionTypeRoleExample

id

Item ID.

The ID is relevant for strategies that use the Bought together with current item or Viewed together with current item algorithm. The ID is the current item against which the platform generates the recommendation.

The platform matches the ID against the id attribute value tracked for an item.

String

Required

"id": "719"

category

Name of the category to which the item belongs.

The category name is relevant for strategies that have the Only return items filter option selected. The platform filters the recommendation based on the category.

The platform matches the category name against the type attribute value tracked for an item. If a strategy has the Only return items whose categories include at least one category to which the viewed item belongs filter option selected, the platform filters the recommendation based on categories attribute values.

tip

You can also use a partial category name, since the API checks whether the category names in the database start with the string you provide here.

For example:

  • "Music" matches Music, Musical Instruments, and any other category name that starts with "Music".

  • "Books/Fiction" matches Books/Fiction/Fantasy, Books/Fiction/Speculative, and any other category name that starts with "Books/Fiction".

String

Optional

"category": "Books/Fiction/Fantasy"

Search page context object

The following table describes the search object of the page context object. The search object provides context information about the current search page.

Search page context object properties
PropertyDescriptionTypeRoleExample

ids

IDs of the items returned by the current search.

The IDs are relevant for strategies that use the Viewed together with recently searched items algorithm. The IDs are the target items against which the platform generates the recommendation.

The platform matches the IDs against the id attribute value tracked for an item.

note

The platform only uses the first three IDs in the list, so it's enough that you provide just three IDs. You're free to choose the logic by which you select the IDs. The logic could be, for example, always taking the IDs of the top three items in the search results.

Array of strings

Required

"ids": [
"958",
"655",
"358"
]

categories

Names of the categories to which the returned items belong.

The category names are relevant for strategies that use the Viewed together with recently searched categories algorithm. The platform generates the recommendation against the listed categories.

The platform matches the category names against the type attribute value tracked for an item.

note

The platform only uses the first three categories in the list, so it's enough that you provide the names of just three categories. You're free to choose the logic by which you select the categories. The logic could be, for example, always taking the categories of the top three items in the search results.

tip

You can also use partial category names, since the API checks whether the category names in the database start with the strings you provide here.

For example:

  • "Music" matches Music, Musical Instruments, and any other category name that starts with "Music".

  • "Books/Fiction" matches Books/Fiction/Fantasy, Books/Fiction/Speculative, and any other category name that starts with "Books/Fiction".

Array of strings

Required

"categories": [
"Books/Fiction/Fantasy",
"Books/Fiction/Speculative"
"Books/Fiction/Scifi"
]

Request examples

Example: Product page recommendation
GET https://inpref.com/recoApi/v2?method=strategy&
origin=shop_company_com&
strategy=viewed-together-with-current-item&
context={
"page": {
"product": {
"id": "719",
"category": "Books/Fiction/Fantasy"
}
}
}
Example: Product page recommendation, return product variant data
GET https://inpref.com/recoApi/v2?method=strategy&
origin=shop_company_com&
strategy=viewed-together-with-current-item&
context={
"page": {
"product": {
"id": "719",
"category": "Books/Fiction/Fantasy"
}
}
}&
variants=true
Example: Product page recommendation, affinity applied
GET https://inpref.com/recoApi/v2?method=strategy&
origin=shop_company_com&
strategy=viewed-together-with-current-item-with-affinity&
cookieId=dsr77t.kstzihlx&
context={
"page": {
"product": {
"id": "719",
"category": "Books/Fiction/Fantasy"
}
}
}
Example: Category page recommendation
GET https://inpref.com/recoApi/v2?method=strategy&
origin=shop_company_com&
strategy=bought-together-with-current-category&
context={
"page": {
"category": {
"categories": [
"Books/Fiction/Fantasy",
"Books/Fiction/Speculative"
]
}
}
}
Example: Category page recommendation, user context required
GET https://inpref.com/recoApi/v2?method=strategy&
origin=shop_company_com&
strategy=most-viewed-by-the-visitor&
cookieId=dsr77t.kstzihlx&
context={
"page": {
"category": {
"categories": [
"Books/Fiction/Fantasy",
"Books/Fiction/Speculative"
]
}
}
}
Example: Home page (
GET https://inpref.com/recoApi/v2?method=strategy&
origin=shop_company_com&
strategy=trending-on-site&
context={}
Example: Home page (
GET https://inpref.com/recoApi/v2?method=strategy&
origin=shop_company_com&
strategy=recently-viewed-by-the-visitor&
cookieId=dsr77t.kstzihlx&
context={}

Responses

Success

On a success, the Recommendations API returns the requested recommendation data in a JSON object. The response status code is 200.

The response object contains the following root properties:

  • data: Recommendation data as an array of objects, where each object contains the details of a single recommended item. The order of items depends on the sorting setting defined in the strategy.

  • debug: Object containing the debugging information. This property is included only when the debug parameter is set to true in the request.

Response structure without debugging information
{
"data": [
{<item 1 data>},
{<item 2 data>},
...
{<item n data>}
]
}
Response structure with debugging information
{
"data": [
{<item 1 data>},
{<item 2 data>},
...
{<item n data>}
],
"debug": {
<debugging information>
}
}

If an item is a parent product with one or more product variants, and if the request is set to also return variants, the recommended item object includes the variants array, which contains the full product data for each variant.

Response structure with product variant data
{
"data": [
{
"id": "1001",
"type": "Fashion/Shoes",
"name": "Casual Engineer Boots",
"created_at": "2022-01-14T17:36:37+02:00",
"updated_at": "2022-01-14T17:36:37+02:00",
"attributes": {
"availability": "in stock",
"brand": "Lumberland",
"color": "Black",
"image": "https://shop.company.com/images/products/product-1001.png",
"originalPrice": 350,
"price": 290,
"url": "https://shop.company.com/products/1001"
},
"variants": [
{
"id": "1002",
"type": "Fashion/Shoes",
"name": "Casual Engineer Boots",
"created_at": "2022-01-14T17:36:37+02:00",
"updated_at": "2022-01-14T17:36:37+02:00",
"attributes": {
"availability": "in stock",
"brand": "Lumberland",
"color": "Brown",
"image": "https://shop.company.com/images/products/product-1002.png",
"originalPrice": 350,
"price": 290,
"url": "https://shop.company.com/products/1002"
}
},
{
"id": "1003",
"type": "Fashion/Shoes",
"name": "Casual Engineer Boots",
"created_at": "2022-01-14T17:36:37+02:00",
"updated_at": "2022-01-14T17:36:37+02:00",
"attributes": {
"availability": "in stock",
"brand": "Lumberland",
"color": "White",
"image": "https://shop.company.com/images/products/product-1003.png",
"originalPrice": 350,
"price": 290,
"url": "https://shop.company.com/products/1003"
}
}
]
}
]
}

If there's no recommendation data available for the requested strategy, the API returns an empty array.

Response structure with no recommendation data
{
"data": []
}

Success examples

The following two examples show the same response without and with debugging information.

Example: Response with recommendation data only
{
"data": [
{
"id": "5",
"type": "Power Tools/Woodworking",
"name": "Brandix Router Power Tool 2017ERXPK",
"created_at": "2020-12-23T10:04:39+02:00",
"updated_at": "2021-10-26T10:14:00+03:00",
"attributes": {
"brand": "Wakita",
"category": "Power Tools/Woodworking",
"image": "https://demo-retail-bp.docker-box.inpref.com/images/products/product-5.jpg",
"manufacturer": "Wakita",
"price": 1700.00,
"url": "https://demo-retail-bp.docker-box.inpref.com/shop/product/5"
}
},
{
"id": "1",
"type": "Power Tools/Woodworking",
"name": "Electric Planer Brandix KL370090G 300 Watts",
"created_at": "2020-11-09T15:51:53+02:00",
"updated_at": "2021-10-15T16:39:37+03:00",
"attributes": {
"brand": "Wakita",
"category": "Power Tools/Woodworking",
"image": "https://demo-retail-bp.docker-box.inpref.com/images/products/product-1.jpg",
"manufacturer": "Wakita",
"price": 509.32,
"url": "https://demo-retail-bp.docker-box.inpref.com/shop/product/1"
}
},
{
"id": "20",
"type": "Makeup/Makeup Products",
"name": "Lipstick, Red Perky",
"created_at": "2020-11-03T13:23:59+02:00",
"updated_at": "2021-10-06T15:32:26+03:00",
"attributes": {
"brand": "Tiks",
"category": "Makeup/Makeup Products",
"image": "https://demo-retail-bp.docker-box.inpref.com/images/products/huulipuna1.jpg",
"manufacturer": "Tiks",
"price": 18.71,
"url": "https://demo-retail-bp.docker-box.inpref.com/shop/product/20"
}
},
{
"id": "2",
"type": "Power Tools/Saws",
"name": "IRadix DPS3000SY 2700 Watts",
"created_at": "2020-11-03T13:21:51+02:00",
"updated_at": "2021-10-26T10:13:46+03:00",
"attributes": {
"brand": "Wakita",
"category": "Power Tools/Saws",
"image": "https://demo-retail-bp.docker-box.inpref.com/images/products/product-2.jpg",
"manufacturer": "Wakita",
"price": 580.83,
"url": "https://demo-retail-bp.docker-box.inpref.com/shop/product/2"
}
},
{
"id": "14",
"type": "Other/Compressors",
"name": "Brandix Air Compressor DELTAKX500",
"created_at": "2020-11-12T15:26:02+02:00",
"updated_at": "2021-10-20T16:10:46+03:00",
"attributes": {
"brand": "Cakita",
"category": "Other/Compressors",
"image": "https://demo-retail-bp.docker-box.inpref.com/images/products/product-14.jpg",
"manufacturer": "Cakita",
"price": 1800.00,
"url": "https://demo-retail-bp.docker-box.inpref.com/shop/product/14"
}
},
{
"id": "16",
"type": "Power Tools/Drills",
"name": "Brandix Screwdriver SCREW1500ACC",
"created_at": "2020-12-23T10:04:30+02:00",
"updated_at": "2021-10-26T10:13:31+03:00",
"attributes": {
"brand": "Cakita",
"category": "Power Tools/Drills",
"image": "https://demo-retail-bp.docker-box.inpref.com/images/products/product-16.jpg",
"manufacturer": "Cakita",
"price": 1499.00,
"url": "https://demo-retail-bp.docker-box.inpref.com/shop/product/16"
}
},
{
"id": "19",
"type": "Makeup/Makeup Products",
"name": "Nail Polish Double Set",
"created_at": "2020-11-03T13:24:08+02:00",
"updated_at": "2021-10-20T15:13:40+03:00",
"attributes": {
"brand": "Tiks",
"category": "Makeup/Makeup Products",
"image": "https://demo-retail-bp.docker-box.inpref.com/images/products/kynsilakat.jpg",
"manufacturer": "Tiks",
"price": 12.50,
"url": "https://demo-retail-bp.docker-box.inpref.com/shop/product/19"
}
},
{
"id": "4",
"type": "Power Tools/Drills",
"name": "Drill Series 3 Brandix KSR4590PQS 1500 Watts",
"created_at": "2020-11-03T13:24:55+02:00",
"updated_at": "2021-10-28T08:57:57+03:00",
"attributes": {
"brand": "Wakita",
"category": "Power Tools/Drills",
"image": "https://demo-retail-bp.docker-box.inpref.com/images/products/product-4.jpg",
"manufacturer": "Wakita",
"price": 949.00,
"url": "https://demo-retail-bp.docker-box.inpref.com/shop/product/4"
}
}
]
}
Example: Response with recommendation data and debugging information
{
"data": [
{
"id": "5",
"type": "Power Tools/Woodworking",
"name": "Brandix Router Power Tool 2017ERXPK",
"created_at": "2020-12-23T10:04:39+02:00",
"updated_at": "2021-10-26T10:14:00+03:00",
"attributes": {
"brand": "Wakita",
"category": "Power Tools/Woodworking",
"image": "https://demo-retail-bp.docker-box.inpref.com/images/products/product-5.jpg",
"manufacturer": "Wakita",
"price": 1700.00,
"url": "https://demo-retail-bp.docker-box.inpref.com/shop/product/5"
}
},
{
"id": "1",
"type": "Power Tools/Woodworking",
"name": "Electric Planer Brandix KL370090G 300 Watts",
"created_at": "2020-11-09T15:51:53+02:00",
"updated_at": "2021-10-15T16:39:37+03:00",
"attributes": {
"brand": "Wakita",
"category": "Power Tools/Woodworking",
"image": "https://demo-retail-bp.docker-box.inpref.com/images/products/product-1.jpg",
"manufacturer": "Wakita",
"price": 509.32,
"url": "https://demo-retail-bp.docker-box.inpref.com/shop/product/1"
}
},
{
"id": "20",
"type": "Makeup/Makeup Products",
"name": "Lipstick, Red Perky",
"created_at": "2020-11-03T13:23:59+02:00",
"updated_at": "2021-10-06T15:32:26+03:00",
"attributes": {
"brand": "Tiks",
"category": "Makeup/Makeup Products",
"image": "https://demo-retail-bp.docker-box.inpref.com/images/products/huulipuna1.jpg",
"manufacturer": "Tiks",
"price": 18.71,
"url": "https://demo-retail-bp.docker-box.inpref.com/shop/product/20"
}
},
{
"id": "2",
"type": "Power Tools/Saws",
"name": "IRadix DPS3000SY 2700 Watts",
"created_at": "2020-11-03T13:21:51+02:00",
"updated_at": "2021-10-26T10:13:46+03:00",
"attributes": {
"brand": "Wakita",
"category": "Power Tools/Saws",
"image": "https://demo-retail-bp.docker-box.inpref.com/images/products/product-2.jpg",
"manufacturer": "Wakita",
"price": 580.83,
"url": "https://demo-retail-bp.docker-box.inpref.com/shop/product/2"
}
},
{
"id": "14",
"type": "Other/Compressors",
"name": "Brandix Air Compressor DELTAKX500",
"created_at": "2020-11-12T15:26:02+02:00",
"updated_at": "2021-10-20T16:10:46+03:00",
"attributes": {
"brand": "Cakita",
"category": "Other/Compressors",
"image": "https://demo-retail-bp.docker-box.inpref.com/images/products/product-14.jpg",
"manufacturer": "Cakita",
"price": 1800.00,
"url": "https://demo-retail-bp.docker-box.inpref.com/shop/product/14"
}
},
{
"id": "16",
"type": "Power Tools/Drills",
"name": "Brandix Screwdriver SCREW1500ACC",
"created_at": "2020-12-23T10:04:30+02:00",
"updated_at": "2021-10-26T10:13:31+03:00",
"attributes": {
"brand": "Cakita",
"category": "Power Tools/Drills",
"image": "https://demo-retail-bp.docker-box.inpref.com/images/products/product-16.jpg",
"manufacturer": "Cakita",
"price": 1499.00,
"url": "https://demo-retail-bp.docker-box.inpref.com/shop/product/16"
}
},
{
"id": "19",
"type": "Makeup/Makeup Products",
"name": "Nail Polish Double Set",
"created_at": "2020-11-03T13:24:08+02:00",
"updated_at": "2021-10-20T15:13:40+03:00",
"attributes": {
"brand": "Tiks",
"category": "Makeup/Makeup Products",
"image": "https://demo-retail-bp.docker-box.inpref.com/images/products/kynsilakat.jpg",
"manufacturer": "Tiks",
"price": 12.50,
"url": "https://demo-retail-bp.docker-box.inpref.com/shop/product/19"
}
},
{
"id": "4",
"type": "Power Tools/Drills",
"name": "Drill Series 3 Brandix KSR4590PQS 1500 Watts",
"created_at": "2020-11-03T13:24:55+02:00",
"updated_at": "2021-10-28T08:57:57+03:00",
"attributes": {
"brand": "Wakita",
"category": "Power Tools/Drills",
"image": "https://demo-retail-bp.docker-box.inpref.com/images/products/product-4.jpg",
"manufacturer": "Wakita",
"price": 949.00,
"url": "https://demo-retail-bp.docker-box.inpref.com/shop/product/4"
}
}
],
"debug": {
"slots": [
{
"dataPoint": {
"id": "5",
"weight": 4
},
"algorithm": "popular_viewed"
},
{
"dataPoint": {
"id": "1",
"weight": 3
},
"algorithm": "popular_viewed"
},
{
"dataPoint": {
"id": "20",
"weight": 3
},
"algorithm": "popular_viewed"
},
{
"dataPoint": {
"id": "2",
"weight": 2
},
"algorithm": "popular_viewed"
},
{
"dataPoint": {
"id": "14",
"weight": 1
},
"algorithm": "popular_viewed"
},
{
"dataPoint": {
"id": "16",
"weight": 1
},
"algorithm": "popular_viewed"
},
{
"dataPoint": {
"id": "19",
"weight": 1
},
"algorithm": "popular_viewed"
},
{
"dataPoint": {
"id": "4",
"weight": 1
},
"algorithm": "popular_viewed"
}
],
"dataPoints": [
{
"id": "5",
"weight": 4
},
{
"id": "1",
"weight": 3
},
{
"id": "20",
"weight": 3
},
{
"id": "2",
"weight": 2
},
{
"id": "14",
"weight": 1
},
{
"id": "16",
"weight": 1
},
{
"id": "19",
"weight": 1
},
{
"id": "4",
"weight": 1
}
],
"recos": [
{
"id": 2471,
"name": "strategy89_position1_popular_viewed",
"limit": 120,
"mapping": "product",
"filters": null,
"postDynamicFilters": null,
"modelUpdatedAt": "2021-11-01T12:25:07Z",
"updatedAt": "2021-11-01T12:25:55Z",
"params": null,
"excludeIds": null,
"dataPoints": [
{
"id": "5",
"weight": 4
},
{
"id": "1",
"weight": 3
},
{
"id": "20",
"weight": 3
},
{
"id": "2",
"weight": 2
},
{
"id": "14",
"weight": 1
},
{
"id": "16",
"weight": 1
},
{
"id": "19",
"weight": 1
},
{
"id": "4",
"weight": 1
}
],
"details": [
"loading the created recommendation configuration at 2021-11-01T17:19:20+02:00",
"loading the recommendation model data from Graniitti API",
"loading the recommendation model data",
"loading the recommendation model data (internal)",
"success with loading the recommendation model data. Took 188.238346ms to complete"
]
}
],
"strategy": {
"site_id": 2265,
"id": 89,
"id_string": "most-popular-overall",
"slots": [

],
"positions": [
{
"id": 1,
"items": 8,
"algorithm": "popular_viewed",
"reco_id": 2471,
"anchor_source": "",
"anchor_source_path": "",
"anchor_items": 0
}
],
"affinity_percentage": 0,
"updated_at": "2020-11-03T11:42:56Z"
},
"positions": [
{
"id": 1,
"dataPoints": [
{
"id": "5",
"weight": 4
},
{
"id": "1",
"weight": 3
},
{
"id": "20",
"weight": 3
},
{
"id": "2",
"weight": 2
},
{
"id": "14",
"weight": 1
},
{
"id": "16",
"weight": 1
},
{
"id": "19",
"weight": 1
},
{
"id": "4",
"weight": 1
}
],
"addedDataPoints": [
{
"id": "5",
"weight": 4
},
{
"id": "1",
"weight": 3
},
{
"id": "20",
"weight": 3
},
{
"id": "2",
"weight": 2
},
{
"id": "14",
"weight": 1
},
{
"id": "16",
"weight": 1
},
{
"id": "19",
"weight": 1
},
{
"id": "4",
"weight": 1
}
],
"duplicateDataPoints": [

],
"affinity": {
"maxScore": 0,
"maxWeight": 0,
"products": [

],
"dataPoints": [

],
"details": [

]
}
}
],
"affinity": {
"applied": false,
"userScores": null,
"percentage": 0,
"products": [

],
"dataPoints": [

],
"details": [
"not applied. Affinity percentage is less than or equal to 0",
"not applied. Cookie ID is missing"
]
},
"context": {
"page": null,
"user": null
},
"productAPI": [
{
"id": "5",
"message": "added product data",
"cached": false
},
{
"id": "1",
"message": "added product data",
"cached": false
},
{
"id": "20",
"message": "added product data",
"cached": false
},
{
"id": "2",
"message": "added product data",
"cached": false
},
{
"id": "14",
"message": "added product data",
"cached": false
},
{
"id": "16",
"message": "added product data",
"cached": false
},
{
"id": "19",
"message": "added product data",
"cached": false
},
{
"id": "4",
"message": "added product data",
"cached": false
}
]
}
}

The following example shows a debug-enabled response for a strategy that applies visitor affinity.

Example: Response with recommendation data and debugging information for a strategy that applies affinity
{
"data": [
{
"id": "2",
"type": "Power Tools/Saws",
"name": "IRadix DPS3000SY 2700 Watts",
"created_at": "2020-11-03T13:21:51+02:00",
"updated_at": "2021-10-26T10:13:46+03:00",
"attributes": {
"brand": "Wakita",
"category": "Power Tools/Saws",
"image": "https://demo-retail-bp.docker-box.inpref.com/images/products/product-2.jpg",
"manufacturer": "Wakita",
"price": 580.83,
"url": "https://demo-retail-bp.docker-box.inpref.com/shop/product/2"
}
},
{
"id": "5",
"type": "Power Tools/Woodworking",
"name": "Brandix Router Power Tool 2017ERXPK",
"created_at": "2020-12-23T10:04:39+02:00",
"updated_at": "2021-10-26T10:14:00+03:00",
"attributes": {
"brand": "Wakita",
"category": "Power Tools/Woodworking",
"image": "https://demo-retail-bp.docker-box.inpref.com/images/products/product-5.jpg",
"manufacturer": "Wakita",
"price": 1700.00,
"url": "https://demo-retail-bp.docker-box.inpref.com/shop/product/5"
}
},
{
"id": "1",
"type": "Power Tools/Woodworking",
"name": "Electric Planer Brandix KL370090G 300 Watts",
"created_at": "2020-11-09T15:51:53+02:00",
"updated_at": "2021-10-15T16:39:37+03:00",
"attributes": {
"brand": "Wakita",
"category": "Power Tools/Woodworking",
"image": "https://demo-retail-bp.docker-box.inpref.com/images/products/product-1.jpg",
"manufacturer": "Wakita",
"price": 509.32,
"url": "https://demo-retail-bp.docker-box.inpref.com/shop/product/1"
}
},
{
"id": "4",
"type": "Power Tools/Drills",
"name": "Drill Series 3 Brandix KSR4590PQS 1500 Watts",
"created_at": "2020-11-03T13:24:55+02:00",
"updated_at": "2021-10-28T08:57:57+03:00",
"attributes": {
"brand": "Wakita",
"category": "Power Tools/Drills",
"image": "https://demo-retail-bp.docker-box.inpref.com/images/products/product-4.jpg",
"manufacturer": "Wakita",
"price": 949.00,
"url": "https://demo-retail-bp.docker-box.inpref.com/shop/product/4"
}
},
{
"id": "16",
"type": "Power Tools/Drills",
"name": "Brandix Screwdriver SCREW1500ACC",
"created_at": "2020-12-23T10:04:30+02:00",
"updated_at": "2021-10-26T10:13:31+03:00",
"attributes": {
"brand": "Cakita",
"category": "Power Tools/Drills",
"image": "https://demo-retail-bp.docker-box.inpref.com/images/products/product-16.jpg",
"manufacturer": "Cakita",
"price": 1499.00,
"url": "https://demo-retail-bp.docker-box.inpref.com/shop/product/16"
}
}
],
"debug": {
"slots": [
{
"dataPoint": {
"id": "2",
"weight": 2
},
"algorithm": "popular_viewed"
},
{
"dataPoint": {
"id": "5",
"weight": 4
},
"algorithm": "popular_viewed"
},
{
"dataPoint": {
"id": "1",
"weight": 3
},
"algorithm": "popular_viewed"
},
{
"dataPoint": {
"id": "4",
"weight": 1
},
"algorithm": "popular_viewed"
},
{
"dataPoint": {
"id": "16",
"weight": 1
},
"algorithm": "popular_viewed"
}
],
"dataPoints": [
{
"id": "2",
"weight": 2
},
{
"id": "5",
"weight": 4
},
{
"id": "1",
"weight": 3
},
{
"id": "4",
"weight": 1
},
{
"id": "16",
"weight": 1
}
],
"recos": [
{
"id": 2916,
"name": "strategy277_position1_popular_viewed",
"limit": 120,
"mapping": "product",
"filters": null,
"postDynamicFilters": null,
"modelUpdatedAt": "2021-11-01T12:24:56Z",
"updatedAt": "2021-11-01T12:26:33Z",
"params": null,
"excludeIds": null,
"dataPoints": [
{
"id": "5",
"weight": 4
},
{
"id": "1",
"weight": 3
},
{
"id": "20",
"weight": 3
},
{
"id": "2",
"weight": 2
},
{
"id": "14",
"weight": 1
},
{
"id": "16",
"weight": 1
},
{
"id": "19",
"weight": 1
},
{
"id": "4",
"weight": 1
}
],
"details": [
"loading the created recommendation configuration at 2021-11-01T17:18:29+02:00",
"loading the recommendation model data from Graniitti API",
"loading the recommendation model data",
"loading the recommendation model data (internal)",
"success with loading the recommendation model data. Took 195.195876ms to complete"
]
},
{
"id": 2951,
"name": "strategy277_position2_longterm_bought",
"limit": 120,
"mapping": "product",
"filters": null,
"postDynamicFilters": null,
"modelUpdatedAt": "2021-11-01T12:25:01Z",
"updatedAt": "2021-11-01T12:25:56Z",
"params": null,
"excludeIds": null,
"dataPoints": [
{
"id": "1",
"weight": 1
}
],
"details": [
"loading the created recommendation configuration at 2021-11-01T17:19:40+02:00",
"loading the recommendation model data from Graniitti API",
"loading the recommendation model data",
"loading the recommendation model data (internal)",
"success with loading the recommendation model data. Took 191.043085ms to complete"
]
}
],
"strategy": {
"site_id": 2265,
"id": 277,
"id_string": "with-affinity",
"slots": [

],
"positions": [
{
"id": 1,
"items": 5,
"algorithm": "popular_viewed",
"reco_id": 2916,
"anchor_source": "",
"anchor_source_path": "",
"anchor_items": 0
},
{
"id": 2,
"items": 10,
"algorithm": "longterm_bought",
"reco_id": 2951,
"anchor_source": "",
"anchor_source_path": "",
"anchor_items": 0
}
],
"affinity_percentage": 100,
"updated_at": "2021-09-15T13:46:32Z"
},
"positions": [
{
"id": 1,
"dataPoints": [
{
"id": "2",
"weight": 2
},
{
"id": "5",
"weight": 4
},
{
"id": "1",
"weight": 3
},
{
"id": "4",
"weight": 1
},
{
"id": "16",
"weight": 1
},
{
"id": "20",
"weight": 3
},
{
"id": "19",
"weight": 1
},
{
"id": "14",
"weight": 1
}
],
"addedDataPoints": [
{
"id": "2",
"weight": 2
},
{
"id": "5",
"weight": 4
},
{
"id": "1",
"weight": 3
},
{
"id": "4",
"weight": 1
},
{
"id": "16",
"weight": 1
}
],
"duplicateDataPoints": [

],
"affinity": {
"maxScore": 152,
"maxWeight": 4,
"products": [
{
"id": "5",
"attributes": {
"brand": {
"score": 112,
"value": "Wakita"
},
"type": {
"score": 32,
"value": "Power Tools/Woodworking"
}
},
"nonNormalizedWeight": 4,
"normalizedWeight": 1,
"nonNormalizedScore": 144,
"normalizedScore": 0.9473684210526315,
"affinity": 0.9473684210526315
},
{
"id": "1",
"attributes": {
"brand": {
"score": 112,
"value": "Wakita"
},
"type": {
"score": 32,
"value": "Power Tools/Woodworking"
}
},
"nonNormalizedWeight": 3,
"normalizedWeight": 0.75,
"nonNormalizedScore": 144,
"normalizedScore": 0.9473684210526315,
"affinity": 0.9473684210526315
},
{
"id": "20",
"attributes": {
"brand": {
"score": 8,
"value": "Tiks"
},
"type": {
"score": 8,
"value": "Makeup/Makeup Products"
}
},
"nonNormalizedWeight": 3,
"normalizedWeight": 0.75,
"nonNormalizedScore": 16,
"normalizedScore": 0.10526315789473684,
"affinity": 0.10526315789473684
},
{
"id": "2",
"attributes": {
"brand": {
"score": 112,
"value": "Wakita"
},
"type": {
"score": 40,
"value": "Power Tools/Saws"
}
},
"nonNormalizedWeight": 2,
"normalizedWeight": 0.5,
"nonNormalizedScore": 152,
"normalizedScore": 1,
"affinity": 1
},
{
"id": "14",
"attributes": {
"brand": {
"score": 0,
"value": "Cakita"
},
"type": {
"score": 0,
"value": "Other/Compressors"
}
},
"details": [
"invalid \"brand\" product attribute score. Should be greater than zero, got 0.00",
"invalid \"type\" product attribute score. Should be greater than zero, got 0.00"
],
"nonNormalizedWeight": 1,
"normalizedWeight": 0.25,
"nonNormalizedScore": 0,
"normalizedScore": 0,
"affinity": 0
},
{
"id": "16",
"attributes": {
"brand": {
"score": 0,
"value": "Cakita"
},
"type": {
"score": 32,
"value": "Power Tools/Drills"
}
},
"details": [
"invalid \"brand\" product attribute score. Should be greater than zero, got 0.00"
],
"nonNormalizedWeight": 1,
"normalizedWeight": 0.25,
"nonNormalizedScore": 32,
"normalizedScore": 0.21052631578947367,
"affinity": 0.21052631578947367
},
{
"id": "19",
"attributes": {
"brand": {
"score": 8,
"value": "Tiks"
},
"type": {
"score": 8,
"value": "Makeup/Makeup Products"
}
},
"nonNormalizedWeight": 1,
"normalizedWeight": 0.25,
"nonNormalizedScore": 16,
"normalizedScore": 0.10526315789473684,
"affinity": 0.10526315789473684
},
{
"id": "4",
"attributes": {
"brand": {
"score": 112,
"value": "Wakita"
},
"type": {
"score": 32,
"value": "Power Tools/Drills"
}
},
"nonNormalizedWeight": 1,
"normalizedWeight": 0.25,
"nonNormalizedScore": 144,
"normalizedScore": 0.9473684210526315,
"affinity": 0.9473684210526315
}
],
"dataPoints": [
{
"id": "2",
"weight": 1
},
{
"id": "5",
"weight": 0.9473684210526315
},
{
"id": "1",
"weight": 0.9473684210526315
},
{
"id": "4",
"weight": 0.9473684210526315
},
{
"id": "16",
"weight": 0.21052631578947367
},
{
"id": "20",
"weight": 0.10526315789473684
},
{
"id": "19",
"weight": 0.10526315789473684
},
{
"id": "14",
"weight": 0
}
],
"details": [
"applied for product \"5\". Normalized affinity score: 0.95. Affinity: 0.95",
"applied for product \"1\". Normalized affinity score: 0.95. Affinity: 0.95",
"applied for product \"20\". Normalized affinity score: 0.11. Affinity: 0.11",
"applied for product \"2\". Normalized affinity score: 1.00. Affinity: 1.00",
"applied for product \"14\". Normalized affinity score: 0.00. Affinity: 0.00",
"applied for product \"16\". Normalized affinity score: 0.21. Affinity: 0.21",
"applied for product \"19\". Normalized affinity score: 0.11. Affinity: 0.11",
"applied for product \"4\". Normalized affinity score: 0.95. Affinity: 0.95"
]
}
},
{
"id": 2,
"dataPoints": [
{
"id": "1",
"weight": 1
}
],
"addedDataPoints": [

],
"duplicateDataPoints": [
{
"id": "1",
"weight": 1
}
],
"affinity": {
"maxScore": 144,
"maxWeight": 1,
"products": [
{
"id": "1",
"attributes": {
"brand": {
"score": 112,
"value": "Wakita"
},
"type": {
"score": 32,
"value": "Power Tools/Woodworking"
}
},
"nonNormalizedWeight": 1,
"normalizedWeight": 1,
"nonNormalizedScore": 144,
"normalizedScore": 1,
"affinity": 1
}
],
"dataPoints": [
{
"id": "1",
"weight": 1
}
],
"details": [
"applied for product \"1\". Normalized affinity score: 1.00. Affinity: 1.00"
]
}
}
],
"affinity": {
"applied": true,
"userScores": {
"scores": {
"brand": {
"Tiks": 8,
"Wakita": 112
},
"type": {
"Hand tools/Wrenches and Pliers": 8,
"Makeup/Makeup Products": 8,
"Power Tools/Drills": 32,
"Power Tools/Saws": 40,
"Power Tools/Woodworking": 32
}
},
"created_at": "2021-11-02T08:35:02+02:00",
"updated_at": "2021-11-02T08:35:53+02:00"
},
"percentage": 100,
"products": [
{
"id": "5",
"attributes": {
"brand": {
"score": 112,
"value": "Wakita"
},
"type": {
"score": 32,
"value": "Power Tools/Woodworking"
}
},
"nonNormalizedWeight": 4,
"normalizedWeight": 1,
"nonNormalizedScore": 144,
"normalizedScore": 0.9473684210526315,
"affinity": 0.9473684210526315
},
{
"id": "1",
"attributes": {
"brand": {
"score": 112,
"value": "Wakita"
},
"type": {
"score": 32,
"value": "Power Tools/Woodworking"
}
},
"nonNormalizedWeight": 3,
"normalizedWeight": 0.75,
"nonNormalizedScore": 144,
"normalizedScore": 0.9473684210526315,
"affinity": 0.9473684210526315
},
{
"id": "2",
"attributes": {
"brand": {
"score": 112,
"value": "Wakita"
},
"type": {
"score": 40,
"value": "Power Tools/Saws"
}
},
"nonNormalizedWeight": 2,
"normalizedWeight": 0.5,
"nonNormalizedScore": 152,
"normalizedScore": 1,
"affinity": 1
},
{
"id": "16",
"attributes": {
"brand": {
"score": 0,
"value": "Cakita"
},
"type": {
"score": 32,
"value": "Power Tools/Drills"
}
},
"details": [
"invalid \"brand\" product attribute score. Should be greater than zero, got 0.00"
],
"nonNormalizedWeight": 1,
"normalizedWeight": 0.25,
"nonNormalizedScore": 32,
"normalizedScore": 0.21052631578947367,
"affinity": 0.21052631578947367
},
{
"id": "4",
"attributes": {
"brand": {
"score": 112,
"value": "Wakita"
},
"type": {
"score": 32,
"value": "Power Tools/Drills"
}
},
"nonNormalizedWeight": 1,
"normalizedWeight": 0.25,
"nonNormalizedScore": 144,
"normalizedScore": 0.9473684210526315,
"affinity": 0.9473684210526315
}
],
"dataPoints": [
{
"id": "2",
"weight": 1
},
{
"id": "5",
"weight": 0.9473684210526315
},
{
"id": "4",
"weight": 0.9473684210526315
},
{
"id": "20",
"weight": 0.10526315789473684
},
{
"id": "14",
"weight": 0
}
],
"details": [
"applied for product \"5\". Normalized affinity score: 0.95. Affinity: 0.95",
"applied for product \"1\". Normalized affinity score: 0.95. Affinity: 0.95",
"applied for product \"2\". Normalized affinity score: 1.00. Affinity: 1.00",
"applied for product \"16\". Normalized affinity score: 0.21. Affinity: 0.21",
"applied for product \"4\". Normalized affinity score: 0.95. Affinity: 0.95"
]
},
"context": {
"page": null,
"user": null
},
"productAPI": [
{
"id": "5",
"message": "added product data",
"cached": false
},
{
"id": "1",
"message": "added product data",
"cached": false
},
{
"id": "20",
"message": "added product data",
"cached": false
},
{
"id": "2",
"message": "added product data",
"cached": false
},
{
"id": "14",
"message": "added product data",
"cached": false
},
{
"id": "16",
"message": "added product data",
"cached": false
},
{
"id": "19",
"message": "added product data",
"cached": false
},
{
"id": "4",
"message": "added product data",
"cached": false
}
]
}
}

Error

On an error, the Recommendations API returns the response status code 400 and an error message.

Recommendations API error messages
Error messageDescriptionSolution
parameter 'method' missing

The method query parameter is missing from the request URL.

Provide the method query parameter.

parameter 'method' contains an empty value

The value of the method query parameter is missing.

Provide a non-empty value for the method query parameter.

invalid method '<parameter_value>'

The value of the method query parameter, <parameter_value>, is invalid.

Provide strategy as the value of the method query parameter.

parameter 'origin' missing

The origin query parameter is missing from the request URL.

Provide the origin query parameter.

parameter 'origin' contains an empty value

The value of the origin query parameter is missing.

Provide a non-empty value for the origin query parameter.

invalid origin parameter '<parameter_value>'

The value of the origin query parameter, <parameter_value>, is invalid.

Provide a valid site origin as the value of the origin query parameter.

To find out your site's origin, see Getting your site origin.

parameter 'strategy' missing

The strategy query parameter is missing from the request URL.

Provide the strategy query parameter.

parameter 'strategy' contains an empty value

The value of the strategy query parameter is missing.

Provide a non-empty value for the strategy query parameter.

invalid strategy parameter '<parameter_value>'

The value of the strategy query parameter, <parameter_value>, is invalid.

Provide a valid strategy ID as the value of the strategy query parameter.

parameter 'cookieId' contains an empty value

The value of the cookieId query parameter is missing.

Provide a non-empty value for the cookieId query parameter.

parameter 'cookieId' has invalid format

The value of the cookieId query parameter has an invalid format.

Provide a value that conforms to the following rules:

  • The length of the value is 1-24 characters.

  • The value contains only the following ASCII characters (in any combination):

    • Letters: A to Z (upper case) and a to z (lower case)

    • Numbers: 0 to 9

    • Special characters: . (period), _ (underscore), + (plus sign), - (hyphen)

parameter 'context' missing

The context query parameter is missing from the request URL.

Provide the context query parameter.

parameter 'context' contains an empty value

The value of the context query parameter is missing.

Provide a non-empty value for the context query parameter.

parameter 'context' contains invalid JSON: <json_error>

The value of the context query parameter is not a valid JSON object.

Provide a valid JSON object as the value of the context query parameter.

error retrieving value from context using path '<context_property_path>': expected string or array of strings for path: '<context_property_path>'

The value of the context query parameter does not contain the required context information, <context_property_path>, or one or more of the object properties containing the information are incorrectly named.

Make sure that the value of the context query parameter contains the required context information and that all the object properties are correctly named.

parameter 'variants' invalid, expected either 'true', 'false', '1' or '0'

The value of the variants query parameter is invalid.

If you want to return product variant data, set the variants query parameter to either true or 1.

If you do not want to return product variant data, set the variants query parameter to either false or 0, or omit the parameter from the request URL.

parameter 'profile' invalid, expected either '', 'opt-in' or 'opt-out'

The value of the profile query parameter is invalid.

If you want to define the visitor's profiling choice, set the profile query parameter to opt-in or opt-out.

If you do not want to define the visitor's profiling choice, set the profile query parameter to an empty value, or omit the parameter from the request URL.

parameter 'shuffle' invalid, expected either 'true', 'false', '1' or '0'

The value of the shuffle query parameter is invalid.

If you want to shuffle the order of items, set the shuffle query parameter to either true or 1.

If you do not want to shuffle the order of items, set the shuffle query parameter to either false or 0, or omit the parameter from the request URL.