Recommendations (Basic)

The Basic Recommendations API returns recommendations for a specified user. It differs from the advanced route in that it offers support for one set of filters per call.

Request
curl 'https://recommendations.api.boomtrain.com/v1/your_site/email/[email protected]?compact=true&test=true&filter=pubDate:AFTER:-P7D&exclude=article|abcd'
curl 'https://recommendations.api.boomtrain.com/v1/your_site/bsin/Lhzn0ClM1A397PINUa%2BzVSoh%2BH06noQl%2F9wNxvKWLa8jEsNFj58yKhA6bOoeDNG2S6TYsmkkj6u7xDdcOcp1tA%3D%3D?compact=true&test=true&filter=pubDate:after:-P7D&exclude=article|abcd'

🚧

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": {
    "rec-set-id": "820875ed-66e5-4a23-a9a7-fd611e2013f0",
        "recs": [
            {
                "click-url": "https://redirect.api.boomtrain.com/click/application/abc?r=article:1234&c=None&b=None&rd=http://example.com",
                "id": "1234",
                "props": {
                    "author": "Dave Williams",
                    "modDate": '2016-02-12T14:20:32+00:00',
                    "pubDate": '2016-02-01T14:14:25+00:00',
                    "keyword": "entertainment",
                    "title": "All Day Holiday Movie Marathon Slated for Feb. 29"
                },
                "rec-id": "ab539ac5-da75-11e5-ae12-0a69b99457cf",
                "resource-type": "article",
                "thumbnail": "http://images.boomtrain.com/nPxlsbnUidapRiOPVDYew7h3gk1qo7m95OPmYdPe67Y.png"
            },
            {
                "click-url": "https://redirect.api.boomtrain.com/click/application/abc?r=article:0229&c=None&b=None&rd=http://example.com/2",
                "id": "0229",
                "props": {
                    "author": "John Smith",
                    "modDate": '2016-02-12T14:20:32+00:00',
                    "pubDate": '2016-02-01T14:14:25+00:00',
                    "keyword": "news",
                    "title": "Rumblings in the Marianas Trench"
                },
                "rec-id": "ab539ac5-da75-11e5-ae12-0a69b99457cf",
                "resource-type": "article",
                "thumbnail": "http://images.boomtrain.com/EvA0Q1EjAgyK78AwUhzNqdq0WIt0oSXx6smKGv4hgc0.gif"
            }
        ],
        "type": "personalized",
        "view-pixel": "https://redirect.api.boomtrain.com/vp/site/MPYIlJ5wVbiAk/WKDz+eTt7tPvJn8diIBkjyf0PO9vEUSI155pgjju+XgdHpH0S8sVcrTntNZ2A1954wgyZ80A==?c=None&b=None&p=True&rt=None&rid=None&r=None&rsid=ae3ace96-e701-11e5-9ddd-12d5480515d7"
    }
}
{
  "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
    }
  ]
}

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 or a single integer or floating point value.Can either be applied to timestamp fields such as pubDate and modDate or count/score/currency fields. Returns resources with a timestamp after the end of the provided duration relative to current time, or values greater than or equal to the provided integer or floating point value for non-timestamp fields.?filter=pubdate:AFTER:-P7D // pubDate after seven days ago.
?filter=age:AFTER:25 //age field greater than or equal to 25.
BEFOREA single ISO-8601 Duration string.Can only be applied to timestamp fields such as pubDate and modDate or count/score/currency fields. Returns resources with a timestamp before the beginning of the provided duration, or values less than the provided integer or floating point value for non-timestamp fields.?filter=expDate:BEFORE:P1D // expDate before 1 day from now.
?filter=age:BEFORE:25 //age field less than 25.
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, integers, or floating point numbers 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!