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.
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:
-
In the header, click your username, and select API Access.
-
In the Recommendations API section, copy the URL.
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
Parameter | Description | Type | Role | Example |
---|---|---|---|---|
| Request type. Use the value | String | Required |
|
| Site origin. To find out your site's origin, see Getting your site origin. | String | Required |
|
| Recommendation strategy ID. | String | Required |
|
| 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 if it uses any of the following algorithms:
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 |
|
| 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. | Required |
| |
| 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 The possible values are:
The default value is | Boolean | Optional |
|
| 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:
The default value is empty. Each visitor's profiling choice is stored in their context. You can get the choice using the 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 worksIf you set the value to If you set the value to
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 |
|
| 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 | Boolean | Optional |
|
| 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:
The possible values are:
The default value is | Boolean | Optional |
|
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.
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.
Property | Description | Type | Role | Example |
---|---|---|---|---|
| Context information about the current page. | Required |
|
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.
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.
Property | Description | Type | Role | Example |
---|---|---|---|---|
| Context information about the current brand page. | Optional |
| |
| Context information about the current shopping cart page. | Optional |
| |
| Context information about the current category page. | Optional |
| |
| 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. | Optional |
| |
| Context information about the current search page. | Optional |
|
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.
Property | Description | Type | Role | Example |
---|---|---|---|---|
| Name of the brand. | String | Required |
|
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.
Property | Description | Type | Role | Example |
---|---|---|---|---|
| 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 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 |
|
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.
Property | Description | Type | Role | Example |
---|---|---|---|---|
| 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 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:
Examples
| Array of strings | Required |
|
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.
Property | Description | Type | Role | Example |
---|---|---|---|---|
| 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 | String | Required |
|
| 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 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:
| String | Optional |
|
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.
Property | Description | Type | Role | Example |
---|---|---|---|---|
| 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 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 |
|
| 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 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:
| Array of strings | Required |
|
Request examples
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"
}
}
}
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
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"
}
}
}
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"
]
}
}
}
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"
]
}
}
}
GET https://inpref.com/recoApi/v2?method=strategy&
origin=shop_company_com&
strategy=trending-on-site&
context={}
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 thedebug
parameter is set totrue
in the request.
{
"data": [
{<item 1 data>},
{<item 2 data>},
...
{<item n data>}
]
}
{
"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.
{
"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.
{
"data": []
}
Success examples
The following two examples show the same response without and with 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"
}
}
]
}
{
"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.
{
"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.
Error message | Description | Solution |
---|---|---|
| The | Provide the |
| The value of the | Provide a non-empty value for the |
| The value of the | Provide |
| The | Provide the |
| The value of the | Provide a non-empty value for the |
| The value of the | Provide a valid site origin as the value of the To find out your site's origin, see Getting your site origin. |
| The | Provide the |
| The value of the | Provide a non-empty value for the |
| The value of the | Provide a valid strategy ID as the value of the |
| The value of the | Provide a non-empty value for the |
| The value of the | Provide a value that conforms to the following rules:
|
| The | Provide the |
| The value of the | Provide a non-empty value for the |
| The value of the | Provide a valid JSON object as the value of the |
| The value of the | Make sure that the value of the |
| The value of the | If you want to return product variant data, set the If you do not want to return product variant data, set the |
| The value of the | If you want to define the visitor's profiling choice, set the If you do not want to define the visitor's profiling choice, set the |
| The value of the | If you want to shuffle the order of items, set the If you do not want to shuffle the order of items, set the |