API Reference

Alternative Item Recommendations (Basic)

get https://recommendations.api.boomtrain.com/v2/alternative///

The Alternative Items Recommendations API returns recommendations for a specified user that are potential alternatives to a given seed, offering a product comparison or pivot experience that revolves around a product they've shown interest in.

Request
curl 'https://recommendations.api.boomtrain.com/v2/alternative/your-site/email/[email protected]?test=true&seeds=product|331839917&fields=brand&count=3'

curl 'https://recommendations.api.boomtrain.com/v2/alternative/your-site/bsin/3f10933f48fde901e90d10909a0901bsb1c01eb01ftest=true&seeds=product|331839917&fields=brand&count=3'

🚧

Please Note:

When you're ready to deploy this endpoint, remove 'test=true' from the URL. Otherwise, user metrics will not be recorded.

Results

{
    "data": {
        "recs": [
            {
                "click-url": "https://redirect.api.boomtrain.com/click/your-site/jP/fJfdB64HBMFTUc40xBjTocxaojSuy4V1y31Ld3jvTWltQ30gcHIrOLhFwRN4DKnxNt4Xqla1Ro8i3KjG47A==?g=default&rt=product&t=420982&rc=Popular&rsid=287ed22e-f58d-11e7-832f-0ad79fd724e2&rd=https%3A%2F%2Fwww.example.com%2Fproduct%2F331382207.html%23331382207%3D331382216&m=other&rid=287ed22e-f58d-11e7-832f-0ad79fd724e2:default:0&r=331382216&x=&p=False&n=0",
                "id": "331382216",
                "is_personalized": false,
                "props": {
                    "age_group": "adult",
                    "brand": "HELLY HANSEN",
                    "color": "536 RACER BLUE",
                    "condition": "new",
                    "custom_label_0": " ",
                    "custom_label_1": " ",
                    "custom_label_2": "Clearance",
                    "custom_label_3": " ",
                    "description": "Combining the unique LIFA fiber technology next to your skin to keep you dry, with a premium merino wool exterior offers superior insulating and wicking properties.",
                    "gender": "male",
                    "is_bundle": "FALSE",
                    "item_group_id": "331382207",
                    "modDate": "2017-12-16T02:09:07+00:00",
                    "price": "39.88 CAD",
                    "product_type_1": "SOFTGOODS",
                    "product_type_2": "WINTER-CLOTHING-ACCESSORIES",
                    "product_type_3": "MENS",
                    "product_type_4": "UNDERWEAR",
                    "product_type_5": "UNDERWEAR-TOPS",
                    "pubDate": "2017-12-16T02:09:07+00:00",
                    "sale_price": "na",
                    "sale_price_effective_date-END": "1970-01-01T00:00:00+00:00",
                    "sale_price_effective_date-START": "1970-01-01T00:00:00+00:00",
                    "size": "s",
                    "size_system": "US",
                    "thumbnail": "https://fgl.scene7.com/is/image/FGLSportsLtd/331382207_44_a?resMode=sharp2&op_sharpen=1&hei=800&wid=800",
                    "title": "Helly Hansen LIFA Warm Ice Crew Underwear Top Mens",
                    "url": "https://www.example.com/product/331382207.html#331382207=331382216"
                },
                "rec-id": "287ed22e-f58d-11e7-832f-0ad79fd724e2:default:0",
                "recset-id": "287ed22e-f58d-11e7-832f-0ad79fd724e2",
                "resource-type": "product",
                "thumbnail": "https://fgl.scene7.com/is/image/FGLSportsLtd/331382207_44_a?resMode=sharp2&op_sharpen=1&hei=800&wid=800"
            },
            ...
        ],
        "type": "popular",
        "view-pixel": "https://redirect.api.boomtrain.com/vp/your-site/jP/fJfdB64HBMFTUc40xBjTocxaojSuy4V1y31Ld3jvTWltQ30gcHIrOLhFwRN4DKnxNt4Xqla1Ro8i3KjG47A==?rsid=287ed22e-f58d-11e7-832f-0ad79fd724e2&gn=default:3&t=420982&x=&rc=Popular&p=False"
    }
}

{
  "errors": [
    {
      "message": "The requested URL was not found on the server.  If you entered the URL manually please check your spelling and try again.",
      "request_url": "http://recommendations.api.boomtrain.com/v1/feedbuzz/emailz/[email protected]",
      "status": 404
    }
  ]
}

{
  "errors": [
    {
      "message": "We had a reactor leak here now. Give us a few minutes to lock it down. Large leak, very dangerous.",
      "status": 500
    }
  ]
}
If insufficient recommendable resources can be returned that match all of the fields specified, the request will fail with a 400 response.

Filter Specification

Each filter parameter corresponds to a constraint for the recommendations to be returned in a section. If more than one filter parameter is used, the result will be interpreted as the intersection of the filters, i.e. filter1 ∩ filter2 ∩... For example, adding filters ?filter=resource-type::article&filter=keywords::dogs would filter the section to articles with the "dogs" keyword.

Filters are specified in the format name:operator:value as follows:

name - A string that indicates which field of your resource the filter will be applied to, e.g. "resource-type", "pubDate", "keywords".
operator - The operator for the filter. Filter operators allow you to specify relations between the filter values. Supported filters include:

OperatorValues AcceptedInterpretationExample
AFTERA single ISO-8601 Duration string.Can only be applied to timestamp fields such as pubDate and modDate. Returns resources with a timestamp after the end of the provided duration.?filter=pubdate:AFTER:-P7D // pubDate after seven days ago.
BEFOREA single ISO-8601 Duration string.Can only be applied to timestamp fields such as pubDate and modDate. Returns resources with a timestamp before the beginning of the provided duration.?filter=expDate:BEFORE:P1D // expDate before 1 day from now.
BETWEENTwo ISO-8601 Duration strings.Can only be applied to timestamp fields such as pubDate and modDate. Returns resources with a timestamp after the first provided value and before the second provided value. ?filter=pubDate:BETWEEN:-P2D|-P1D // pubDate between 2 days ago and 1 day ago.
NOTAny number of strings.Returns results where the field does not match any of the provided values.?filter=keyword:NOT:dogs|cats // keywords contains neither dogs nor cats.
If no operator is specified, we check the fields for equality. For example:
  • The filter ?filter=keywords::dogs|cats will filter to resources that contain either "dogs" or "cats" as a keyword. Note that resource fields with an array type will consider an equality operation to be "true" if _any_ of the values in the array matches the specified value.
  • The filter ?filter=colors::red will filter to resources with the "red" value in the "colors" field.

values - Strings representing the fields of the resource to filter the recommendation to, separated by '|' characters.

View Pixel Tracking

In order to provide metrics and data to improve Boomtrain's recommendation systems, the `view-pixel` returned in the result of this call should be impressed whenever these results are viewed by a user. This can be done by adding an invisible image pixel into the HTML body where the request is being shown. For example, <img src="view-pixel returned by this route" />.

Results

Note that the view-pixel should be rendered on each impression of a recommendation set in order to track views of recommendations.

As well, the click-url should be triggered upon click of any recommendation in order to track clicks for the purpose of evaluating performance.

Language
Click Try It! to start a request and see the response here!