Menu
Product Advertising API
Developer Guide (API Version 2013-08-01)

SimilarityLookup

Description

The SimilarityLookup operation returns up to ten products per page that are similar to one or more items specified in the request. This operation is typically used to pique a customer’s interest in buying something similar to what they’ve already ordered.

If you specify more than one item, SimilarityLookup returns the intersection of similar items each item would return separately. Alternatively, you can use the SimilarityType parameter to return the union of items that are similar to any of the specified items. A maximum of ten similar items are returned; the operation does not return additional pages of similar items. If there are more than ten similar items, running the same request can result in different answers because the ten that are included in the response are picked randomly. The results are picked randomly only when you specify multiple items and the results include more than ten similar items.

When you specify multiple items, it is possible for there to be no intersection of similar items. In this case, the operation returns the following error:


<Error>
  <Code>AWS.ECommerceService.NoSimilarities</Code>
  <Message>There are no similar items for this ASIN: B00006WREH.</Message>
</Error>

This result is very often the case if the items belong to different search indices. The error can occur, however, even when the items share the same search index.

Similarity is a measurement of similar items purchased, that is, customers who bought X also bought Y and Z. It is not a measure, for example, of items viewed, that is, customers who viewed X also viewed Y and Z.

Items returned can be filtered by:

  • Condition—Describes the status of an item. Valid values are All, New (default), Used, Refurbished or Collectible. When the Availability parameter is set to "Available", the Condition parameter cannot be set to "New".

Examples

Return items that are similar to a list of items.


http://webservices.amazon.com/onca/xml?
Service=AWSECommerceService&
AWSAccessKeyId=[AWS Access Key ID]&
AssociateTag=[Associate ID]&
Operation=SimilarityLookup&ItemId=ASIN1,ASIN2,ASIN3
&Timestamp=[YYYY-MM-DDThh:mm:ssZ]
&Signature=[Request Signature]
    

This request returns the intersection of the similarities for each ASIN. The response to this request is shown in Sample Response.

Return up to ten items that are similar to any of the ASINs specified.


          
http://webservices.amazon.com/onca/xml?
Service=AWSECommerceService&
AWSAccessKeyId=[AWS Access Key ID]&
AssociateTag=[Associate ID]&
Operation=SimilarityLookup&ItemId=ASIN1,ASIN2,ASIN3&
SimilarityType=Random
&Timestamp=[YYYY-MM-DDThh:mm:ssZ]
&Signature=[Request Signature]
    

This request returns the union of items that are similar to all of the ASINs specified. Only ten items can be returned and those are picked randomly from all of the similar items. Repeating the operation could produce different results.

Request Parameters

NameDescriptionRequired
Condition

Specifies an item's condition. If Condition is set to “All”, a separate set of responses is returned for each valid value of Condition.

Type: String

Default: New

Valid Values: All | Collectible | Refurbished | Used

No
ItemId

Specifies the item you want to look up. An ItemId is an alphanumeric identifier assigned to an item. You can specify up to ten ItemIds separated by commas.

Type: String

Default: None

Valid Values: ASIN

Yes
MerchantId

An optional parameter that can be used to filter search results and offer listings to only include items sold by Amazon. By default, Product Advertising API returns items sold by various merchants including Amazon. Enter "Amazon" to return only items sold by Amazon.

Type: String

Valid Values: Amazon

No
SimilarityType

"Intersection" returns the intersection of items that are similar to all of the ASINs specified. "Random" returns the union of items that are similar to all of the ASINs specified. Only ten items are returned. So, if there are more than ten similar items found, a random selection from the group is returned. For this reason, running the same request multiple times can yield different results.

Type: String

Default: Intersection

Valid Value:Random

No
ResponseGroup

Specifies the types of values to return. You can specify multiple response groups in one request by separating them with commas.

Type: String

Default: Request | Small

Valid Values: Accessories | BrowseNodes | EditorialReview | Images | Large | ItemAttributes | ItemIds | Medium | Offers | OfferSummary | PromotionSummary | Reviews | SalesRank | Similarities | Small | Tracks | Variations | VariationSummary |

No

SimilarityLookup also accepts the parameters that all operations can use. For more information, see Common Request Parameters.

Sample Response

The following XML is a snippet of the full response to the first sample request.


<Item>
  <ASIN>B0009VX8XQ</ASIN>
  <ItemAttributes>
    <ProductGroup>Apparel</ProductGroup>
    <Title>Mark VII Men's Short Sleeve Herringbone Knit Golf Shirt</Title>
  </ItemAttributes>
</Item>
<Item>
  <ASIN>B0009VX8VI</ASIN>
  <ItemAttributes>
    <ProductGroup>Apparel</ProductGroup>
    <Title>Mark VII Men's Short Sleeve Knit Golf Shirt</Title>
  </ItemAttributes>
</Item>
  

This response shows that two items were similar to the ASINs submitted. The information included with each item is sufficient to display the item for sale.

Response

NameDescription
ASIN An alphanumeric token that uniquely identifies an item for sale.
Item Container for information about an item, including, ItemAttributes, and ASIN.
ItemAttributes Container for information describing an item, including, ProductGroup and Title.
ProductGroup Category to which an item belongs. Similar to Search Index.
Title Name of the item for sale.

For more information about the parent elements of these tags, see the appropriate response group in Response Groups.

Related Operations

ItemSearch using the Similarities response group