Get similar item recommendations

Similar item recommendations consist of an Item ID and an estimation of the similarity of the item-pair. Additional attributes include the name of the algorithm that was used to generate the recommendation and the certainty of the similarity estimation. Similar items are sorted by descending score. The higher the score, the higher the similarity. Supported formats:

csv
json
xml

Request

Method

URL

/sites/{account}/items/{itemid}/similar.{format}

account - your account key.
itemid - a string that uniquely identifies the item.
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 similar items.
400 Bad Request - required parameters are missing or provided parameters are malformed.
404 Not Found - there are no items that are similar.
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 - estimation of the similarity of the item-pair.
algorithm - recommendation algorithm that was used.

The following attributes might also be present in a response:

certainty - certainty of the estimation.
item - item metadata, e.g. title, permalink.

Some algorithms do not provide a certainty value. Item metadata is not always available.

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/items/1/similar.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/items/1/similar.json?category=A

Retrieved items must belong to category A or B:

GET /sites/sandbox/items/1/similar.json?category=A,B

- or - 

GET /sites/sandbox/items/1/similar.json?category[]=A&category[]=B

Retrieved items must belong to category A or B, but not category C:

GET /sites/sandbox/items/1/similar.json?category=A,B,!C

- or - 

GET /sites/sandbox/items/1/similar.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/items/1/similar.json?category=A,!B,C,!D

- or - 

GET /sites/sandbox/items/1/similar.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/items/1/similar.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/items/1/similar.json?time=2011-02-01T15:00&time_radius=2&time_unit=h

Retrieved items must be available for recommendation right now:

GET /sites/sandbox/items/1/similar.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/items/1/similar.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,SimilarCF,0.1
2,0.8,SimilarCF,0.1
3,0.7,SimilarCF,0.1
4,0.6,SimilarCF,0.1
5,0.5,SimilarCF,0.1

Json format

Certainty and item metadata are returned if available.

[
    {
        "itemid":"1",
        "score":"0.9",
        "certainty":"0.1",
        "algorithm":"SimilarCF",            
        "item": {
            "id": "1",
            "title": "Item 1",
            "category": ["A", "B"]
        }       
    },
    {
        "itemid":"2",
        "score":"0.8",
        "certainty":"0.1",
        "algorithm":"SimilarCF",
        "item": {
            "id": "2",
            "title": "Item 2",
            "category": ["B", "C"]
        }       
    },
    ...
]

Xml format