Product Advertising API
Developer Guide (API Version 2011-08-01)
« PreviousNext »
View the PDF for this guide.Go to the AWS Discussion Forum for this product.Did this page help you?  Yes | No |  Tell us about it...

ItemLookup

Description

Given an Item identifier, the ItemLookup operation returns some or all of the item attributes, depending on the response group specified in the request. By default, ItemLookup returns an item’s ASIN, Manufacturer, ProductGroup, and Title of the item.

ItemLookup supports many response groups, so you can retrieve many different kinds of product information, called item attributes, including product reviews, variations, similar products, pricing, availability, images of products, accessories, and other information.

To look up more than one item at a time, separate the item identifiers by commas.

Availability

All locales, however, the parameter support varies by locale.

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. The default value is "New" (not "All"). So, if your request does not return results, consider setting the value to "All." When the value is "New," the ItemSearch Availability parameter cannot be set to "Available." Amazon only sells items that are "New."

Type: String

Default: New

Valid Values: Used | Collectible | Refurbished, All

No
IdType

Type of item identifier used to look up an item. All IdTypes except ASINx require a SearchIndex to be specified.

Type: String

Default: ASIN

Valid Values: SKU | UPC | EAN | ISBN (US only, when search index is Books). UPC is not valid in the CA locale.

No
IncludeReviewsSummary

When set to true, returns the reviews summary within the Reviews iframe.

Type: Boolean

Default: True

Valid Values: True | False

No
ItemId

One or more (up to ten) positive integers that uniquely identify an item. The meaning of the number is specified by IdType. That is, if IdType is ASIN, the ItemId value is an ASIN. If ItemIdis an ASIN, a search index cannot be specified in the request.

Type: String

Default: None

Constraints: Must be a valid item ID. For more than one ID, use a comma-separated list of up to ten IDs.

Yes
MerchantId

An optional parameter you can use to filter search results and offer listings to only include items sold by Amazon. By default, the API will return items sold by various merchants including Amazon. Enter Amazon if you only want to see items sold by Amazon in the response.

Type: String

Valid Values: Amazon

No
RelatedItemPage This optional parameter is only valid when the RelatedItems response group is used. Each ItemLookup request can return, at most, ten related items. The RelatedItemPage value specifies the set of ten related items to return. A value of 2, for example, returns the second set of ten related items No
RelationshipType This parameter is required when the RelatedItems response group is used. The type of related item returned is specified by the RelationshipType parameter. Sample values include Episode, Season, and Tracks. For a complete list of types, go to Relationship Types.

Required when RelatedItems response group is used.

Conditional
SearchIndex

The product category to search.

Type: String

Default: None

Valid Values: A search index, for example, Apparel, Beauty, Blended, Books, and so forth. For a complete of search indices, see Search Indices.

Constraint:If ItemIdis an ASIN, a search index cannot be specified in the request. Required for non-ASIN ItemIds.

Conditional
TruncateReviewsAt

By default, reviews are truncated to 1000 characters within the Reviews iframe. To specify a different length, enter the value. To return complete reviews, specify 0.

Type: Integer

Default: 1000

Constraints: Must be a positive integer or 0 (returns entire review)

No
VariationPage

Page number of variations returned by ItemLookup. By default, ItemLookup returns all variations. Use VariationPage to return a subsection of the response. There are 10 variations per page. To examine offers 11 trough 20, for example, set VariationPage to 2.

Type: String

Default: All

Valid Values: Integer between 1 and 150, inclusive

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: Small

Valid Values: Accessories | BrowseNodes | EditorialReview | Images | ItemAttributes | ItemIds | Large | Medium | OfferFull | Offers | PromotionSummary | OfferSummary| RelatedItems | Reviews | SalesRank | Similarities | Small | Tracks | VariationImages | Variations (US only) | VariationSummary

No

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

Response

NameDescription
ASIN Amazon Standard Identification Number, which is an alphanumeric token assigned by Amazon to an item that uniquely identifies it.
Item Container for information about the item, including ASIN, Title, ProductGroup. and Manufacturer.
ItemAttributes Container for information about an item, including Title, ProductGroup. and Manufacturer.
Items Container for one or more Item(s).
Manufacturer Name of the company that manufactured the item.
ProductGroup Category of the item, for example, “Book,” “DVD.” You can find the complete list of product groups by going to www.amazon.com and clicking the tab that says "See All 32 Product Categories."
Title Title of the item.

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

Examples

The following request returns the information associated with ItemId B00008OE6I.

http://webservices.amazon.com/onca/xml?
Service=AWSECommerceService&
AWSAccessKeyId=[AWS Access Key ID]&
Operation=ItemLookup&
ItemId=B00008OE6I
&Timestamp=[YYYY-MM-DDThh:mm:ssZ]
&Signature=[Request Signature]

The response to this request is shown in, Response to Sample Request.

The following request returns an offer for a refurbished item that is not sold by Amazon.

http://webservices.amazon.com/onca/xml?
Service=AWSECommerceService&
AWSAccessKeyId=[AWS Access Key ID]&
Operation=ItemLookup&
ItemId=B00008OE6I&
IdType=ASIN&
ResponseGroup=OfferFull&
Condition=All&
Timestamp=[YYYY-MM-DDThh:mm:ssZ]
&Signature=[Request Signature]

In the following request, the ItemId is an SKU, which requires that you also specify the IdType.

http://webservices.amazon.com/onca/xml?
Service=AWSECommerceService&
AWSAccessKeyId=[AWS Access Key ID]&
Operation=ItemLookup&
ItemId=[SKU]&
IdType=SKU
&Timestamp=[YYYY-MM-DDThh:mm:ssZ]
&Signature=[Request Signature]

In the following request, the ItemId is a UPC, which requires that you also specify the SearchIndex and ItemType.

http://webservices.amazon.com/onca/xml?
Service=AWSECommerceService&
AWSAccessKeyId=[AWS Access Key ID]&
Operation=ItemLookup&
ItemId=[UPC]&
SearchIndex=Books&
&IdType=UPC
&Timestamp=[YYYY-MM-DDThh:mm:ssZ]
&Signature=[Request Signature]

In the following request, the ItemId is an EAN, which requires that you also specify the SearchIndex and ItemType.

http://webservices.amazon.com/onca/xml?
Service=AWSECommerceService&
AWSAccessKeyId=[AWS Access Key ID]&
Operation=ItemLookup&
ItemId=[EAN]&
SearchIndex=Electronics&
IdType=EAN
&Timestamp=[YYYY-MM-DDThh:mm:ssZ]
&Signature=[Request Signature]

Use the BrowseNodes response group to find the browse node of an item.

Use the Tracks response group to find the track, title, and number for each track on each CD in the response.

Use the Similarities response group to find the ASIN and Title for similar products returned in the response.

Use the Reviews response group to find reviews written by customers about an item, and the total number of reviews for each item in the response.

Use the OfferSummary response group to find the number of offer listings and the lowest price for each of the offer listing condition classes, including New, Used, Collectible, and Refurbished.

Use the Accessories response group to find the a list of accessory product ASINs and Titles for each product in the response that has accessories.

The following requests an iframe that contains customer reviews for the specified item.

http://webservices.amazon.com/onca/xml?
Service=AWSECommerceService&
AWSAccessKeyId=[AWS Access Key ID]&
Operation=ItemLookup&
ItemId=0316067938&
ResponseGroup=Reviews&
TruncateReviewsAt="256"&
IncludeReviewsSummary="False"&
Version=2011-08-01
&Timestamp=[YYYY-MM-DDThh:mm:ssZ]
&Signature=[Request Signature]

Sample Response

The following code snippet is a response to the first request. It shows all of the item attributes that are returned by default.

<Items>
  <Request>
  <IsValid>True</IsValid>
  <ItemLookupRequest>
    <ItemId>B00008OE6I</ItemId>
  </ItemLookupRequest>
  </Request>
  <Item>
    <ASIN>B00008OE6I</ASIN>
    <ItemAttributes>
    <Manufacturer>Canon</Manufacturer>
    <ProductGroup>Photography</ProductGroup>
    <Title>Canon PowerShot S400 4MP Digital Camera w/ 3x Optical Zoom</Title>
   </ItemAttributes>
  </Item>
</Items>  

The following code snippet is part of a response for an iframe that contains customer reviews.

<ItemLookupResponse>
	<Items>
		<Item>
			<ASIN>0316067938</ASIN>
			<CustomerReviews>
				<IFrameURL>
				http://www.amazon.com/reviews/iframe?akid=AKIAIOSFODNN7EXAMPLE&asin=0316067938&exp=2011-08-01T17%3A54%3A07Z&linkCode=xm2&summary=0&tag=ws&truncate=256&v=2&sig=rhBGpRiaQ3L78yqgE5y30u8bF6zXsK3HL%2F2KpNMJns0%3D
				</IFrameURL>
			</CustomerReviews>
		</Item>
	</Items>
</ItemLookupResponse>

Related Operations