Product Recommendation API's

Product Recommendation API's

Using the Product recommendation API

Using the API  is straightforward. You can request product recommendations either directly on your site through our javascript, or via HTTP requests from your own backend. In either case, the returned data will be a JSON structure, containing either rendered HTML, or individual fields for each returned product.

Jump to:

Javascript:

Getting recommendations from the javascript API can take two basic forms:

  • ADDWISH_PARTNER_NS.api.recom.load(ids, callback(id, content))
  • ADDWISH_PARTNER_NS.api.recom.load(ids, options, callback(id, content, tag))

ids

IDs should be an object with keys being box-ids, and values being objects with additional values to pass to that box. If you want to load recommendations for another product than the current one, put url: "http://www.example.com/url/to/another-product.html" in the values. This is also where you specify filter values.

Contact Hello Retail support to learn about what filter values are configured for each of your recommendation IDs.

options

If options is given, it should be an object. You can give the following keys as input:

  • tag: Tag can be any object of your choosing. If given to load it will be passed unaltered to the callback method. You can use this if you pass the same callback method to multiple load-calls, to differentiate the results. As the boxes are loaded asyncronously, the callback might not be called in the same order as the requests were sent.
  • format: Either “json” or “html” (default is “html”). If you specify “json”, you will get a list of products in json format, instead of the default rendered html-block.
  • track_page_view: Should be a url. If given, a page view will be tracked for that url before the recommendations are rendered. This is useful, for instance, if you show something resembling a product page in a popup.

callback

This function will be called once for each id in the load-request. Each call will be passed the id, the generated content, and the tag (if specified in options). It’s up to you to place the generated content the right place on the page.

Boxes loaded with the same call to api.recom.load will not contain duplicate products. However, if you call the javascript API multiple times, different calls might return the same products as previous calls.

Example

ADDWISH_PARTNER_NS.api.recom.load(
// ids:
{
"1234567890abcdef12345678": { // This is the recommendation box ID, which is unique to your API call. Contact addwish support to get your own ID.
// Here, you can specify filter values, and other options for this specific recommendation box.
// For example, you can specify the url of another product to get recommendations for:
url: "http://www.example.com/jeans/extra-fancy-jeans-004.html",

// You can specify filter values like this:
category: "Kitchen utensils"

},
"abc4567890abcdef12345432": {} // You can leave the options empty, to use the default url (the current page)
},

// options:
{
format: "json", // You can specify either "json" or "html" as format (default is html)
tag: "this can be anything" // The tag is optional.
},

// The following function will be called once for each set of boxes requested above.
// The value of "id" will correspond to the recommendation box ID requested.
// Data will contain ether rendered html or a list of products.
function(id, data, tag) {
// Do something with data here.
// 'tag' will be "this can be anything" from above.
}
);

When using the javascript API, the url of the current page will automatically be used for related products, unless you manually give another value.

HTTP(s)

If you want to render the recommendations in your own backend, instead of in the frontend, you can instead use the http(s) API. To do this, you simply need to request the url: http://www.addwish.com/api/v1/product-recommendation/getProductBoxes?params...

You need to specify all parameters to your product recommendations as url parameters to the call. Below, you’ll find a table of all supported

FunctionParameter nameDescription

Recommendation box IDs ids Separate multiple IDs with a comma
Main url url This url specifies the product you want to find relations for. Note that you can also specify specific urls for each recommendation box.
Result format format Specify json to get a list of product data, instead of the default html rendition.
Url for a specific box crawledData[ID][url] Use this, if you need to specifiy a different url for a single box. You should replace ID with an actual value.
Traking user ID trackingUserId When you want to get personalized recommendations for a specific user, you will need to supply that users Hello Retail tracking ID. This ID is only available thought our javascript, so you will need to get this value using the javascript solution below, and send it you your own backend for further user.
Filter values crawledData[ID][Filter name] You will need to specify both the ID for the recommendation box and the filter name. Contact Hello Retail support to learn about what filter values are configured for your recommendations.

 

Getting the tracking user id

ADDWISH_PARTNER_NS.api.user.get_tracking_id(callback_function);

You will need to supply the callback function yourself, for example:

ADDWISH_PARTNER_NS.api.user.get_tracking_id(function(trackingUserId) {
// We will call your function, as soon as we have the tracking user id.

// Put the id in a form, and submit it using jQuery:
jQuery("#tracking_user_form input[name='addwish_id']").val(trackingUserId);
jQuery("#tracking_user_form").submit();

// Or, send it directly using jQuerys ajax helpers:
jQuery.post("/url/at/your/backend", {
tracking_user_id: trackingUserId
});
});

Example

Roughly equivalent to the javascript example.

https://www.addwish.com/api/v1/product-recommendation/getProductBoxes?ids=1234567890abcdef12345678,abc4567890abcdef12345432&url=http%3A%2F%2Fwww.example.com%2Fjeans%2Ffancy-jeans-002.html&format=json&crawledData[1234567890abcdef12345678][url]=http%3A%2F%2Fwww.example.com%2Fjeans%2Fextra-fancy-jeans-004.html&trackingUserId=544e3f41e4b05e538f4512d2&crawledData[1234567890abcdef12345678][category]=Kitchen%20utensils

Note that you can use http or https interchangeably.

Result

The result of getting the above url might look something like:

{"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",
// ...
},
// ...
]
}
}

The precise fields will vary according to your shop and configuration.

If you specify “HTML” as the format, you will get a block of HTML rendered from a template configured by Hello Retail. Contact Hello Retail support for details:

{"result": {
"1234567890abcdef12345678": {
"result": "<div>..."
},
"abc4567890abcdef12345432": {
"result": "<div>..."
}
}
Follow
  • 2 mths agoLast active
  • 48Views
  • 1 Following