get
https://recommendations.api.boomtrain.com/v:version///
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:
| Operator | Values Accepted | Interpretation | Example |
|---|---|---|---|
| AFTER | A 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. |
| BEFORE | A 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. |
| BETWEEN | Two 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. |
| NOT | Any 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. |
- 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.