REST-API

For most API methods for recommendations, you will need to provide the Recommendation Box ID.

Note: As stated in the introduction, it is important that you bundle the product recommendations to ensure no duplicates.

get
Get Product Recommendations

https://www.addwish.com/api/v1/product-recommendation/getProductBoxes
Note: Get the value for trackingUserId by using the JavaScript SDK method: get_tracking_id. This value cannot be retrieved by the REST-API.
Request
Response
Request
Query Parameters
Ids
optional
string
List of recommendation box ID's. Separate multiple ID's with a comma.
crawledData[ID][Filter name]
optional
string
With CrawledData, you can supply the system with data to reflect against the attributes of the products
trackingUserId
optional
string
The ID of the current user. This ID is only avaliable with the JavaScript SDK see the section Tracking User.
Format
optional
string
The format you want the result in. The default is HTML to be rendered, but you can also request json.
URL
optional
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.
Response
200: OK
{"result": {
"1234567890abcdef12345678": {
"result": [
{
"url": "http://www.example.com/shop/UltraBlender-2000.html#aw_source\u003dpb-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\u003dpb-abc4567890abcdef12345432",
// ...
},
// ...
]
}
}

Example:

https://www.addwish.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][category]=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 to 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 recommnedation box and you must 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&

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 woman 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 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 is 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 a 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