SimilarityLookup

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.

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:

MerchantId—All, Featured, or a specific merchant ID. Setting the MerchantId parameter to “Featured” returns the same merchant that is displayed when you click the "Add to Shopping Cart" button on the product detail page on the retail Web site. The default value is Amazon.
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."

Sample Requests

Return items that are similar to a list of items.
```
http://ecs.amazonaws.com/onca/xml?
Service=AWSECommerceService&
AWSAccessKeyId=[AWS Access Key ID]&
Operation=SimilarityLookup&ItemId=ASIN1,ASIN2,ASIN3
				
```
This request returns the intersection of the similarities for each ASIN. The response to this request is shown in Response to Sample Request below.
Return up to ten items that are similar to any of the ASINs specified.
```
http://ecs.amazonaws.com/onca/xml?
Service=AWSECommerceService&
AWSAccessKeyId=[AWS Access Key ID]&
Operation=SimilarityLookup&ItemId=ASIN1,ASIN2,ASIN3&
SimilarityType=Random
				
```
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

The following table describes the request parameters for SimilarityLookup. Parameter names are case sensitive.

Parameter	Definition	Required
`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. Default: New (default) 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 ItemId’s separated by commas. Default: None Valid Values:ASIN	Yes
`MerchantId`	Specifies the merchant who is offering the item. MerchantId is an alphanumeric identifier assigned by Amazon to merchants. Make sure to use a Merchant ID and not a Seller ID. Seller IDs are not supported. Default: Amazon (default) Valid Values: MerchantId--ID of a merchant All--Includes Amazon and all other merchants Featured--Merchant listed when you click “Add to Cart”	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. Default: Intersection (Default) 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. Default: Request Small Valid Values: Accessories BrowseNodes EditorialReview Images Large ItemAttributes ItemIds ListmaniaLists Medium Offers OfferSummary PromotionDetails PromotionSummary Reviews SalesRank Similarities Tracks VariationMinimum Variations VariationSummary	No

Response to Sample Request

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

<Item>
  <ASIN>B0009VX8XQ</ASIN> 
  <DetailPageURL>http://www.amazon.com/exec/obidos/redirect?tag=ws%26link_code=xm2%26camp=2025%26creative=165953%26path=http://www.amazon.com/gp/redirect.html%253fASIN=B0009VX8XQ%2526tag=ws%2526lcode=xm2%2526cID=2025%2526ccmID=165953%2526location=/o/ASIN/B0009VX8XQ%25253FAWSAccessKeyId=[AWS Access Key ID]</DetailPageURL> 
  <ItemAttributes>
    <ProductGroup>Apparel</ProductGroup> 
    <Title>Mark VII Men's Short Sleeve Herringbone Knit Golf Shirt</Title> 
  </ItemAttributes>
</Item>
<Item>
  <ASIN>B0009VX8VI</ASIN> 
  <DetailPageURL>http://www.amazon.com/exec/obidos/redirect?tag=ws%26link_code=xm2%26camp=2025%26creative=165953%26path=http://www.amazon.com/gp/redirect.html%253fASIN=B0009VX8VI%2526tag=ws%2526lcode=xm2%2526cID=2025%2526ccmID=165953%2526location=/o/ASIN/B0009VX8VI%25253FAWSAccessKeyId=[AWS Access Key ID]</DetailPageURL> 
  <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 Tags

The following table describes the default response tags included in SimilarityLookup responses.

Element Tag	Definition
`ASIN`	An alphanumeric token that uniquely identifies an item for sale.
`DetailPageURL`	URL of a web page that displays information about an item for sale.
`Item`	Container for information about an item, including, DetailPageURL, 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