Product Advertising API
Developer Guide (API Version 2011-08-01)
| « PreviousNext » | |
  | Did this page help you? Yes | No | Tell us about it... |
The ItemSearch operation returns items that
satisfy the search criteria, including one or more search indices.
ItemSearch returns up to ten search results per page. When
condition equals "All," ItemSearch
returns one offer per condition (if an offer exists)—for example, one new, one used, one
refurbished, and one collectible item. Or, for example, if there are no collectible or
refurbished offers, ItemSearch returns one new and one used offer.
Because there are thousands of items in each search index,
ItemSearch requires that you specify the value for
at least one parameter in addition to a search index. The additional
parameter value must reference items within the specified search index.
For example, you might specify a browse node (BrowseNode is an
ItemSearch parameter), Harry Potter Books, within
the Books product category. You would not get results, for example, if you
specified the search index to be Automotive and the browse node to be
Harry Potter Books. In this case, the parameter value is not associated
with the search index value.
The ItemPage parameter enables you to return a
specified page of results. The maximum ItemPage
number that can be returned is 10. An error is returned if you try to
access higher numbered pages. If you do not include
ItemPage in your request, the first page will be
returned by default. There can be up to ten items per page.
ItemSearch is the operation that is used most often
in requests. In general, when trying to find an item for sale, you use
this operation.
For more discussion about finding items by BrowseNode, see Understanding BrowseNode Results When Drilling Down.
All locales.
ItemSearch has a lot of parameters. Not all of them
pertain, however, to all search indices. For example, when the search
index is apparel, it would be inappropriate to use the
Actor parameter. As a result, each search index
can use only a subset of all of the parameters. For a complete list of the
ItemSearch parameters that can be used with a
specific search index in a specific locale, refer to Search Index and
ItemSearch Parameter Combinations.
The parameters that apply to the largest number of search indices are shown in the following table.
| Parameter | Valid Search Indices |
|---|---|
BrowseNode
| Every index except All and Blended |
Condition
| Every index except All and Blended |
Keywords
| All |
MaximumPrice
| Every index except All and Blended |
MinimumPrice
| Every index except All and Blended |
Title
| Every index except All and Blended |
ItemSearch requires that you specify a search index
and at least one of the following parameters:
|
|
|
| Name | Description | Required |
|---|---|---|
Actor
|
Name of an actor associated with the item. You can enter all or part of the name. Type: String Default: None | No |
Artist
|
Name of an artist associated with the item. You can enter all or part of the name. Type: String Default: None | No |
AudienceRating
|
Movie ratings based on MPAA ratings or age, depending upon the locale. You may specify one or more values in a comma-separated list in a REST request or by using multiple elements in a SOAP request. Type: String. Type: String Default: None Valid Values: See Movie Ratings by Locale, which follows this table. | No |
Author
|
Name of an author associated with the item. You can enter all or part of the name. Type: String Default: None | No |
Availability
|
Enables Type: String Default: None Valid Values: Available | Yes |
Brand
|
Name of a brand associated with the item. You can enter all or part of the name. Type: String, for example, Timex, Seiko, Rolex. Type: String Default: None | No |
BrowseNode
|
Browse nodes are positive integers that identify product categories, for example, Literature & Fiction: (17), Medicine: (13996), Mystery & Thrillers: (18), Nonfiction: (53), Outdoors & Nature: (290060). Type: String Default: None Valid Values: Positive integer. | No |
Composer
|
Name of an composer associated with the item. You can enter all or part of the name. Type: String Default: None | No |
Condition
|
Use the
Type: String Default: New Valid Values: Used | Collectible | Refurbished | All | No |
Conductor
|
Name of a conductor associated with the item. You can enter all or part of the name. Type: String Default: None | No |
Director
|
Name of a director associated with the item. You can enter all or part of the name. Type: String Default: None | No |
IncludeReviewsSummary
|
When set to Type: Boolean Default: True Valid Values: | No |
ItemPage
|
Retrieves a specific page of items from all of the items in
a response. Up to ten items are returned on a page unless
Valid Values: 1 to 10 (1 to 5 when the search index = "All") Type: String Default: None | No |
Keywords
|
A word or phrase associated with an item. The word or phrase
can be in various product fields, including product title,
author, artist, description, manufacturer, and so forth. When,
for example, the search index equals "MusicTracks,"
the Type: String Default: None | No |
Manufacturer
|
Name of a manufacturer associated with the item. You can enter all or part of the name. Type: String Default: None | No |
MaximumPrice
|
Specifies the maximum price of the items in the response. Prices are in terms of the lowest currency denomination, for example, pennies. For example, 3241 represents $32.41. Type: String Default: None Valid Values: Positive integer | No |
MerchantId
|
An optional parameter you can use 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. Use the Type: String Valid Values: | No |
MinimumPrice
|
Specifies the minimum price of the items to return. Prices are in terms of the lowest currency denomination, for example, pennies, for example, 3241 represents $32.41. Type: String Default: None Valid Values: Positive integer | No |
MinPercentageOff
|
Specifies the minimum percentage off for the items to return. Type: String Default: None Valid Values: Positive integer | No |
Orchestra
|
Name of an orchestra associated with the item. You can enter all or part of the name. Type: String Default: None | No |
Power
|
Performs a book search using a complex query string. Only works when the search index is set equal to "Books." Valid Values: See, Power Searches following this table. Type: String Default: None | No |
Publisher
|
Name of a publisher associated with the item. You can enter all or part of the name. Type: String Default: None | 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
Constraint: Required when RelatedItems response group is used | Conditional |
SearchIndex
|
The product category to search. Many
Type: String Default: None Valid Values: A search index, for example, Apparel, Beauty, Blended, Books, and so forth. For Blended searches, go to Blended Searches. For a complete list of search indices, see Search Indices by Locale. | Yes |
Sort
|
Means by which the items in the response are ordered. Type: String Default: None Valid Values: Valid values vary significantly by search index. For a list of valid values, see ItemSearch Sort Values by Locale. | No |
Title
|
The title associated with the item. You can enter all or
part of the title. Type: String Default: None | No |
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
Type: Integer Default: 1000 Constraints: Must be a positive integer or 0 (returns entire review) | No |
VariationPage
|
Retrieves a specific page of variations returned by
Type: String Default: None Valid Values: Positive integer | 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 | ItemAttributes | ItemIds | Large | Medium | OfferFull | Offers | OfferSummary | Reviews | RelatedItems | SearchBins | Similarities | Small | Tracks | Variations | VariationSummary | | No |
ItemSearch also accepts the parameters that all
operations can use. For more information, see, Common Request Parameters
Movie rating values captured in the
AudienceRating parameter, vary by locale. The
following table shows the valid values of
AudienceRating.
| Locale | AudienceRating Values |
|---|---|
CA
| G, PG, PG-13, R, NC-17, NR, Unrated, Family Viewing |
DE
| 6, 12, 16 |
FR
| PG, 12, 16, 18 |
US
| G, PG, PG-13, R, NC-17, NR, Unrated |
| Name | Description |
|---|---|
ASIN
| Amazon Standard Identification Number, which is an alphanumeric token assigned by Amazon to an item that uniquely identifies it. |
Item
| Container for item information, including ASIN and ItemAttributes. |
ItemAttributes
| Container for information about an item, including Manufacturer, ProductGroup, and Title. |
Manufacturer
| Item’s manufacturer. |
MoreSearchResultsURL
| The URL where the complete search results are displayed. The URLs provided in the search results are the exact ones that you should use when you link back to Amazon.com. They are tagged with your Associate tag and contain other tracking information to increase your hourly request limit as the sales that you generate increase. |
ProductGroup
| Product category; similar to search index. |
Title
| Item’s title. |
TotalPages
| Total number of pages in response. There are up to ten items per page. |
TotalResults
| Total number of items found. |
For more information about the parent elements of these tags, see the appropriate response group in Response Groups.
Use the search index, Toys, and the parameter,
Keywords, to return information about all toy
rockets sold in by Amazon.
http://webservices.amazon.com/onca/xml?
Service=AWSECommerceService&
AWSAccessKeyId=[AWS Access Key ID]&
Operation=ItemSearch&
Keywords=Rocket&
SearchIndex=Toys
&Timestamp=[YYYY-MM-DDThh:mm:ssZ]
&Signature=[Request Signature]
The response to this request is shown in, Response to Sample Request.
Use a blended search to look through multiple search indices for items that have “Mustang” in their name or description. A blended search looks through multiple search indices at the same time. For more information, see Blended Searches.
http://webservices.amazon.com/onca/xml?
Service=AWSECommerceService&
AWSAccessKeyId=[AWS Access Key ID]&
Operation=ItemSearch&
Keywords=Mustang&
SearchIndex=Blended
&Timestamp=[YYYY-MM-DDThh:mm:ssZ]
&Signature=[Request Signature]
Use the Availability parameter to only
return shirts that are available:
http://webservices.amazon.com/onca/xml?
Service=AWSECommerceService&
AWSAccessKeyId=[AWS Access Key ID]&
Operation=ItemSearch&
Condition=All&
Availability=Available&
SearchIndex=Apparel&
Keywords=Shirt
&Timestamp=[YYYY-MM-DDThh:mm:ssZ]
&Signature=[Request Signature]
Set the search index to MusicTracks and
Keywords to the title of a song to find a song
title.
Use the BrowseNodes response group to find the browse node of an item.
Use the Variations response group
and the BrowseNode parameter to find all of the
variations of a parent browse node.
The following XML is a snippet of the full response to the first sample request.
<TotalResults>372</TotalResults>
<TotalPages>38</TotalPages>
<Item>
<ASIN>B00021HBN6</ASIN>
<ItemAttributes>
<Manufacturer>Radio Flyer</Manufacturer>
<ProductGroup>Toy</ProductGroup>
<Title>Radio Flyer Retro Rocket</Title>
</ItemAttributes>
</Item>
<Item>
<ASIN>B0007MZV3C</ASIN>
<ItemAttributes>
<Manufacturer>Razor USA LLC</Manufacturer>
<ProductGroup>Toy</ProductGroup>
<Title>Razor Dirt Rocket MX350 Bike</Title>
</ItemAttributes>
</Item> The TotalResults and TotalPages tags
indicate the number of items found and the number of pages those items are on. Use
TotalPages with any of the page parameters, such as
ReviewsPage, to select the page of results to view. Typically,
there are up to ten results on a page.
