REST-API
For most API methods for recommendations, you will need to provide the Product Box ID.
Note: It is important that you bundle the product recommendations to ensure no duplicates.
GET
Get Product Recommendations
Note: Get the value for trackingUserId
by using the JavaScript SDK function: get_tracking_id
. It can also be pulled from the cookies by getting the hello_retail_id
.
Request Method: GET
Endpoint: https://core.helloretail.com/api/v1/product-recommendation/getProductBoxes
Parameters
Query
Name | Type | Description |
---|---|---|
ids |
String | List of recommendation box ID's. Separate multiple ID's with a comma. |
crawledData[ID][Filtername] |
String | With CrawledData, you can supply the system with data to reflect against the attributes of the products |
trackingUserId |
String | The ID of the current user. This ID can be found in the cookie hello_retail_id or through the JavaScript SDK see the section Tracking User. |
format |
String | The format you want the result in. The default is HTML to be rendered, but you can also request json. |
URL |
String | The product URL which is the context of the algorithm. While this parameter is optional, it is highly recommended if you want to create upsell or alternative boxes/algorithms. For category pages you don't need to supply this, since a category page doesn't relate to a single product. For category pages use the crawledData parameter. |
Responses
200 OK
{
"result": {
"1234567890abcdef12345678": {
"result": [
{
"url": "http://www.example.com/shop/UltraBlender-2000.html#aw_source=dpb-1234567890abcdef12345678",
"imageUrl": "http://www.example.com/images/UltraBlender-2000.png",
"title": "UltraBlender 2000",
"onSale": true,
"price": 1699.95,
"priceFormatted": "1.699,95",
"oldPrice": 1999.95,
"oldPriceFormatted": "1.999,95",
"currency": "DKK",
"category": "Kitchen utensils",
"brand": "Indream"
},
{
"url": "...",
// ...
}
// ...
]
},
"abc4567890abcdef12345432": {
"result": [
{
"url": "http://www.example.com/shop/NoFall-Solid.html#aw_source=dpb-abc4567890abcdef12345432",
// ...
},
// ...
]
}
}
Example
https://core.helloretail.com/api/v1/product-recommendation/getProductBoxes?trackingUserId=544e3f41e4b05e538f4512d2&format=json&ids=1234567890abcdef12345678,abc4567890abcdef12345432&url=http%3A%2F%2Fwww.example.com%2Fjeans%2Ffancy-jeans-002.html&crawledData[1234567890abcdef12345678][hierarchies][0][]=Kitchen%20utensils
Details about passing filter values (crawledData) to getProductBoxes()
In some situations, it makes sense to filter which products are returned from the product recommendation engine. Maybe you want products cheaper than a certain limit, only products from a specific brand or category. This can be done by adding filtering to the recommendation engine. It is possible to pass values to use for filtering the recommendation API call. The algorithm needs to be configured by Hello Retail before it can accept filter values as input. So get in touch with support@helloretail.com to get help configuring the algorithm.
All parameters are sent in the query string. The parameter name for passing filter values is crawledData
. The filters must be sent per recommendation box and you should supply the filter name.
Brand filter
Passing a brand filter with the value “Nike” for a box with the ID 123 will look like this in the query string:
&crawledData[123][brand]=Nike&
Hierarchies (categories) filter
In the Hello Retail backend categories are stored in a field called hierarchies that contains a list of category hierarchies the product is in. So a product can be in multiple hierarchies at once. As an example, a pair of women's sandals on sale could have the following hierarchies:
[ ["Shoes", "Woman"], ["On sale", "Woman"], ["Sandals"] ]
So these sandals are in the “Woman” subcategory below the “Shoes” category, they are also in the “Woman” subcategory below the “On sale” category, and finally, they are in the “Sandals” category.
So when passing a filter value for filtering on hierarchies the passed filter value needs to follow the same structure but encoded as query string variables. So if we wanted to pass a filter saying that the products must be in the “Woman” subcategory below the “On sale” category the query string would look something like this:
&crawledData[123][hierarchies][0][]=On sale&crawledData[123][hierarchies][0][]=Woman&
As you can see, you need to supply the index for the first level in the hierarchy, but for the second one, you can pass an empty set of square brackets, and the ordering of the parameters will decide the numbering.
It is possible to pass multiple hierarchies to one filter. So if you wanted to find “Woman” “Shoes” that are also “Sandals” you could pass the filter:
&crawledData[123][hierarchies][0][0]=Shoes&crawledData[123][hierarchies][0][1]=Woman&crawledData[123][hierarchies][1][0]=Sandals&
extraData & extraDataList
The examples above are reserved attributes in the Hello Retail backend. Everything besides these must have extraData
or extraDataList
in front. The declaration of these variables needs to be configured by Hello Retail before it can be used as crawlData
parameters. So get in touch with support@helloretail.com to get help configuring the algorithm. So when passing an extraData
or extraDataList
filter value for filtering on lists or single values, the structure has to follow this:
&crawledData[123][extraDataList][series][]=Cars&crawledData[123][extraDataList][series][]=Scooters&
&crawledData[123][extraData][carBrand]=Toyota