Get personal recommendations
A user's personal recommendations are a list of items that might fit their taste. Recommendations consist of an Item ID and a predicted score. Additional attributes include the name of the algorithm that was used to generate the recommendation and a measure for the certainty of the prediction. Recommendations are sorted by descending score.
Supported formats:
- csv
- json
- xml
Request
Method
- GET
URL
/sites/{account}/users/{userid}/recommendations.{format}- account - your account key.
- userid - a string that uniquely identifies the user.
- format - response format.
Query parameters
- limit - maximum number of recommendations to be retrieved.
- category - retrieved items must (not) belong to one of these categories. Comma separated list.
- category[] - retrieved items must (not) belong to one of these categories. Array of values.
- segment - retrieved items must (not) belong to one of these segments. Comma separated list.
- segment[] - retrieved items must (not) belong to one of these segments. Array of values.
- tag - retrieved items must (not) have any of these tags. Comma separated list.
- tag[] - retrieved items must (not) have any of these tags. Array of values.
- time - retrieved items may be recommended at this time; from <= time <= until. See item metadata and timestamps sections for more information.
- time_radius - retrieved items may be recommended within this time frame.
- time_unit - unit of the time_radius parameter. Supported units:
- m - minutes
- h - hours
- d - days
- location_simple - retrieved items must (not) be in any of these locations. Comma separated list.
- location_simple[] - retrieved items must (not) be in any of these locations. Array of values.
- location_city - retrieved items must (not) be in any of these cities. Comma separated list.
- location_city[] - retrieved items must (not) be in any of these cities. Array of values.
- location_latlong - retrieved items must be near these decimal degree coordinates.
- location_radius - retrieved items must be within this radius of the location_latlong parameter.
- location_unit - unit of the location_radius parameter. Supported units:
- m - meter
- km - kilometer
- ft - feet
- yd - yard
- mi - mile
Response
HTTP status codes
- 200 OK - the response body contains recommendations.
- 400 Bad Request - required parameters are missing or provided parameters are malformed.
- 404 Not Found - there are no recommendations for this user.
- 500 Internal Server Error - indicates a problem on our end or with Amazon Web Services.
Body
The following attributes are always present in a response:- itemid - a string that uniquely identifies the item.
- score - prediction of the user's appreciation of the item.
- algorithm - recommendation algorithm that was used.
- certainty - certainty of the prediction.
- item - item metadata, e.g. title, permalink.
Examples
Location filter
Retrieved items must be near 40° 41' 20" N, 74° 2' 42.4" W, within a two mile radius:GET /sites/sandbox/users/1/recommendations.json?location_latlong=40.688889,-74.045111
&location_radius=2&location_unit=mi
Category filter
Retrieved items must belong to category A:GET /sites/sandbox/users/1/recommendations.json?category=A
Retrieved items must belong to category A or B:
GET /sites/sandbox/users/1/recommendations.json?category=A,B
- or -
GET /sites/sandbox/users/1/recommendations.json?category[]=A&category[]=B
Retrieved items must belong to category A or B, but not category C:
GET /sites/sandbox/users/1/recommendations.json?category=A,B,!C
- or -
GET /sites/sandbox/users/1/recommendations.json?category[]=A&category[]=B&category[]=!C
Retrieved items must belong to category A or C, but not category B or D:
GET /sites/sandbox/users/1/recommendations.json?category=A,!B,C,!D
- or -
GET /sites/sandbox/users/1/recommendations.json?category[]=A&category[]=!B&category[]=C&category=!D
Time filter
Retrieved items must be available for recommendation on February 1, 2011 at 3PM GMT:GET /sites/sandbox/users/1/recommendations.json?time=2011-02-01T15:00
Retrieved items must be available for recommendation on February 1, 2011 at 3PM or sometime during the next two hours:
GET /sites/sandbox/users/1/recommendations.json?time=2011-02-01T15:00&time_radius=2&time_unit=h
Retrieved items must be available for recommendation right now:
GET /sites/sandbox/users/1/recommendations.json?time=NOW
Combining filters
Retrieve the five best items from category A or B that are within 200 feet of this location:GET /sites/sandbox/users/1/recommendations.json?limit=5&category=A,B
&location_latlong=40.688889,-74.045111&location_radius=200&location_unit=ft
Response formats
Csv format
Item id, score, algorithm and (if available) certainty are returned in that order. Item metadata is never present.1,0.9,UserBasedCF,0.1
2,0.8,UserBasedCF,0.1
3,0.7,UserBasedCF,0.1
4,0.6,UserBasedCF,0.1
5,0.5,UserBasedCF,0.1
Json format
Certainty and item metadata are returned if available.[
{
"itemid":"1",
"score":"0.9",
"certainty":"0.1",
"algorithm":"UserBasedCF",
"item": {
"id": "1",
"title": "Item 1",
"category": ["A", "B"]
}
},
{
"itemid":"2",
"score":"0.8",
"certainty":"0.1",
"algorithm":"UserBasedCF",
"item": {
"id": "2",
"title": "Item 2",
"category": ["B", "C"]
}
},
...
]
Xml format
Certainty and item metadata are returned if available.<recommendations>
<recommendation>
<itemid>1</itemid>
<score>0.9</score>
<certainty>0.1</certainty>
<algorithm>UserBasedCF</algorithm>
<item>
<id>1</id>
<title>Item 1</title>
<category>A</category>
<category>B</category>
</item>
</recommendation>
<recommendation>
<itemid>2</itemid>
<score>0.8</score>
<certainty>0.1</certainty>
<algorithm>UserBasedCF</algorithm>
<item>
<id>2</id>
<title>Item 2</title>
<category>B</category>
<category>C</category>
</item>
</recommendation>
...
</recommendations>