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