post https://recommendations.api.boomtrain.com/v:version///?compact=&test=
The Advanced Recommendations API returns recommendation sets for a specified user. It differs from the basic GET route in that it offers support for multiple sections per call and additional filtering requirements.
Please note:
When you're ready to deploy this endpoint, remove 'test=true' from the URL. Otherwise, user metrics will not be recorded.
Request
{
"sections": [
{
"name": "entertainment_section",
"filters": [ // Articles or videos with "entertainment" keyword
{
"name": "resource-type",
"values": ["article", "video"]
},
{
"name": "keyword",
"values": ["entertainment"]
}
],
"count": 5
},
{
"name": "news_articles",
"filters": [ // Articles with either "news" or "breaking news" keyword
{
"name": "resource-type",
"values": ["article"]
},
{
"name": "keyword",
"values": ["news", "breaking news"]
}
],
"count": 5
}
],
"exclude": [ "article|1234", "video|5432" ],
"seeds": [ "article|9987", "video|7765" ],
"caller": "My Application",
"campaign": "Weekly Newsletter",
"batch": "2016-02-29",
"medium": "email",
"segment": "2"
}
Results
{
"data": {
"rec-set-id": "820875ed-66e5-4a23-a9a7-fd611e2013f0",
"sections": {
"entertainment_section": {
"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-03-12T14:20:32+00:00',
"pubDate": '2016-02-29T14: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"
},
// ...
],
"type": "personalized"
},
"news_article": {
"recs": [
{
"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-03-12T14:20:32+00:00',
"pubDate": '2016-02-29T14: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
}
]
}
Section Specification
Each section in your request will contain the following fields:name - The section name. (Note that both sections and filters have names).
count - The number of resources to return for the section.
filters - An array of zero or more filters to be applied to the section.
Filter Specification
For example, adding filters {"name":"resource-type","values":["articles"]} and {"name":"keywords","values":["dogs"]} would filter the section to articles with the "dogs" keyword.Filters are specified 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. | Can only 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, or values greater than or equal to the provided integer or floating point value for non-timestamp fields. | {"name":"pubDate", "operator":"AFTER", "values":["-P7D"]} // pubDate after seven days ago. {"name":"age", "operator":"AFTER", "values":[25]} // age 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. | {"name":"expDate", "operator":"BEFORE", "values":["P1D"], } // expDate before 1 days from now. {"name":"age", "operator":"BEFORE", "values":[25], } //age 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. | {"name":"pubDate","operator":"BETWEEN", "values":["-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. | {"name":"keywords", "operator":"NOT", "values":["dogs", "cats"]} // keywords contains neither dogs nor cats. |
- The filter {"name":"keywords", "values":["dogs", "cats"]} will filter to resources that contain either "dogs" or "cats" as a keyword.
- The filter {"name":"color", "values":["red"]} will filter to resources with the color field set to "red".
values - An array of strings, integers, or floating point numbers representing the fields of the resource to filter the recommendation to.
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.