 | Feedback |  |
The ItemSearch operation returns items that satisfy the search criteria, including one or more search indices.
ItemSearch returns up to ten search results at a time. When condition equals "All," ItemSearch returns up to three offers per condition (if they exist), for example, three new, three used, three refurbished, and three collectible items. Or, for example, if there are no collectible or refurbished offers, ItemSearch returns three new and three used offers.
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 400. 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.
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
| All but All, Blended |
Condition
| All but All, Blended and Merchants |
Keywords
| All |
MaximumPrice
| All but All, Blended and Merchants |
MerchantId
| All but All, Blended and Merchants |
MinimumPrice
| All but All, Blended and Merchants |
Title
| All but All, Blended and Merchants |
ItemSearch requires that you specify a search index and at least one of the following parameters:
|
|
|
The following table describes the request parameters for ItemSearch. Parameter names are case sensitive.
| Parameter | Definition | 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. 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 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. 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). Default: None Valid Values: Positive integer. | No |
City
|
Name of a city associated with the item. You can enter all or part of the name. This parameter only works in the US locale. Default: None Valid Values: Chicago | New York | San Francisco | Seattle | Washington, D.C. | 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
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 |
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: Integer between 1 and 400, inclusive. 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. Default: None Valid Values: Positive integer | No |
MerchantId
|
Specifies the merchant who is selling the item. Default: Amazon Valid Values: Valid merchant ID of a merchant All--Includes Amazon and all other merchants Featured--Merchant listed when you click “Add to Cart” (US only) | Yes |
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. Default: None Valid Values: Positive integer | No |
Neighborhood
|
Name of a neighborhood You can enter all or part of the name. The neighborhoods are located in one of the valid values for Type: String, for example, Capitol Hill, Arlington, and North Beach. Default: None | No |
Orchestra
|
Name of an orchestra associated with the item. You can enter all or part of the name. Type: String Default: None | No |
PostalCode
|
Postal code of the merchant. In the US, the postal code is the postal code. This parameter enables you to search for items sold in a specified region of a country. 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. 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 |
SearchIndex
|
The product category to search. Many Default: None Valid Values: A search index, for example, Apparel, Beauty, Blended, Books, and so forth. For Blended searches, see, Blended Searches before this table. For a complete of search indices, see Search Indices by Locale | No |
Sort
|
Means by which the items in the response are ordered. Default: None Valid Values: Valid values vary significantly by search index. For a list of valid values, see ItemSearch Sort Values by Locale. | No |
TagPage
|
Specifies the page of results to return. There are ten results on a page. The maximum page number is 400. Type: Integer Default: None | No |
TagsPerPage
|
The number of tags to return that are associated with a specified item. Type: Integer Default: None | No |
TagSort
|
Specifies the sorting order for the results. Default: - Usages Valid Values:
To sort items in descending order, prefix the values with a negative sign (-). | No |
TextStream
|
A search based on two or more words. Type: String Default: None | No |
Title
|
The title associated with the item. You can enter all or part of the title. Type: String Default: None | No |
VariationPage
|
Retrieves a specific page of variations returned by 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. Default: Small Valid Values: Accessories | BrowseNodes | EditorialReview | ItemAttributes | ItemIds | Large | ListmaniaLists | Medium | MerchantItemAttributes | OfferFull | Offers | OfferSummary | Reviews | SalesRank | SearchBins | Similarities | Subjects | Tags | TagsSummary | Tracks | VariationMinimum | Variations | VariationSummary | | No |
ItemSearch also accepts the parameters that all operations can use. For more information, see, Common Request Parameters
You can use the All search index to do an ItemSearch search through all search indices. There are, however, a number of restrictions placed on this request. The only parameter that you can use in the request is Keywords. You cannot, for example, sort results. Results are restricted to the first five pages of results. Each page can have only up to five results.
![[Note]](images/note.png) | Note |
|---|---|
You cannot use the All search index in an |
ItemSearch searches through a specified search index, or SearchIndex can be set to "Blended." A blended search always searches through the following search indices (only):
|
|
|
The Availability parameter filters out of ItemSearch results those items that are unavailable. The availability of an item can change rapidly. There is typically a discrepancy between an item’s availability as reported by ItemSearch and the item’s true availability, as reported by Amazon’s web site. For this reason, the availability of items reported by ItemSearch and by Amazon’s web site will be slightly different. Items that are “available” are classified on Amazon’s retail web site as:
The following ItemSearch parameters must be included to return available items (only):
Availability—Must be set to “Available.” When the Availability parameter is not set, ItemSearch returns available and unavailable items. “Available” is the only valid value for Availability. Setting it to another value returns an error message. Parameter values are case sensitive. When the Availability parameter is set to "Available," the Condition parameter cannot be set to "New."
Condition—Must be set to “All”. The default value is "New." When the Availability parameter is set to "Available," the Condition parameter cannot be set to "New."
MerchantId—Alphanumeric token that uniquely identifies a merchant. Valid values are “Amazon,” “All,” or a specific merchant ID. When the Availability parameter is used and MerchantId is set to "Amazon," the availability results for Amazon, Toys R Us, and Target are merged.
The following search indices do not work with the Availability parameter:
Items available for in-store pickup
Items for sale by third parties.
In both cases, because Amazon does not warehouse the items for sale, Amazon cannot determine the availability of them.
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 |
Power searches only work when the search index is “Book.” The power search is a query string that can contain multiple conditions and boolean operations. For example, the query “author:ambrose" returns a list of books where "Ambrose" is in the author’s name. A query of
subject:history and (spain or mexico) and not military and language:spanish
Returns a list of books in the Spanish language on the subject of either Spanish or Mexican history, excluding all items with the term “military” in their subject description. The following are additional examples of Power Searches:
author: ambrose and binding: (abridged or large print) and pubdate: after 11-1996
subject: history and (spain or mexico) and not military and language: spanish
(subject: marketing and author: kotler) or (publisher: harper and subject: "high technology")
keywords: "high tech*" and not fiction and pubdate: during 1999
isbn: 0446394319 or 0306806819 or 1567993850
The key words you can use in a power search include:
author—Book’s author
ISBN—International Standard Book Number of the book
keyword—Words that can be found in any field that describes a book, such as author, subject, or description
language—Language, such as Spanish, that the book is written in
pubdate—Book’s publication date
publisher—Name of the book’s publisher
subject—Word in book’s subject description
title—The title of the book
Power search uses the following syntactical conventions to build queries:
not—Excludes the following parameter from the results, for example, subject:history and not military, excludes military history in the results.
and—Specifies that both values must be true to be selected. For example, subject:history and (spanish and mexican), requires that the books selected contain both Spanish and Mexican history.
or—Exclusive or which means one of either item but not both. For example subject:history and (spanish or mexican), means the subject matter can be about the history of Spain or Mexico, but not both.
colon (:)—Used as an equals sign, for example, subject:history, searches for books whose subject matter is history.
parenthesis—Groups terms to clarify operations, for example,
subject: history and (spain or mexico)
Without the parentheses, you would search for books about Spanish history or Mexico. With parentheses, you search for books about Spanish history and Mexican history.
asterisk (*)—Stands for zero or more alphanumeric characters, for example,
keywords: "high tech*"
Use the asterisk to generalize your search.
Quotation marks (“ “)—Specifies an exact match of the word(s) within the quotes.
For a given search index, only a subset of all ItemSearch parameters are valid. The following table shows those values for the US locale. To see the valid values in a different locale, see Search Index and ItemSearch Parameter Combinations.
| Parameter | Valid With These Search Indices |
|---|---|
Actor
| Video, VHS, DVD, DigitalMusic, Merchants |
Artist
| Music, Classical, Merchants |
AudienceRating
| Video, VHS, DVD |
Author
| Books, Merchants |
Brand
| Apparel, Baby, Beauty, Electronics, HeathPersonalCare, Kitchen, Merchants, Miscellaneous, MusicalInstruments, OfficeProducts, OutdoorLiving, PCHardware, Photo, Software, SportingGoods, Tools, Video`Games |
BrowseNode
| All except Blended |
City
| Merchants |
Composer
| Classical, Merchants |
Condition
| All except Blended and Merchants |
Conductor
| Classical, Merchants |
Director
| Video, VHS, DVD, DigitalMusic, Merchants |
ItemPage
| All |
Keywords
| All |
Parameter
| SearchIndices |
MaximumPrice
| All except Blended and Merchants |
MerchantId
| All except Blended and Merchants |
MinimumPrice
| All except Blended and Merchants |
Manufacturer
| Apparel, Baby, Beauty, Electronics, HeathPersonalCare, Kitchen, Merchants, Miscellaneous, MusicalInstruments, OfficeProducts, OutdoorLiving, PCHardware, Photo, Software, SportingGoods, Tools, VideoGames |
MusicLabel
| Music, Classical, Merchants |
Neighborhood
| Merchants |
Orchestra
| Classical, Merchants |
Power
| Books, Merchants |
Publisher
| Books, DigitalMusic, DVD, Magazines, Merchants, VHS, Video |
Sort
| All. The valid values for Sort, however, are different for each search index. For more information, see the Appendix, “Sort Values by Locale.” |
TextStream
| Apparel, Books, Classical, DigitalMusic, DVD, Electronics, GourmetFood, Jewelry, Merchants, Music, Photo, Toys, Video, VideoGames |
Title
| All except Blended and Merchants |
The following table describes the default response tags included in ItemSearch responses.
| Element Tag | Definition |
|---|---|
ASIN
| Amazon Standard Identification Number, which is an alphanumeric token assigned by Amazon to an item that uniquely identifies it. |
DetailPageURL
| URL of an item's web site that includes an item’s title, availability, similar items, features, accessories, product description, customer reviews of the item, links to news articles about the item, related Listmania lists, “So You’d Like To....” list, and “Browse For Photo” list. |
Item
| Container for item information, including ASIN, DetailPageURL, and ItemAttributes. |
ItemAttributes
| Container for information about an item, including Manufacturer, ProductGroup, and Title. |
Manufacturer
| Item’s manufacturer. |
ProductGroup
| Product category; similar to search index. |
Title
| Item’s title. |
TotalPages
| Total number of pages in response. There are 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 ItemSearch in the following ways:
Use the search index, Toys, and the parameter, Keywords, to return information about all toy rockets sold in by Amazon.
http://ecs.amazonaws.com/onca/xml?
Service=AWSECommerceService&
AWSAccessKeyId=[AWS Access Key ID]&
Operation=ItemSearch&
Keywords=Rocket&
SearchIndex=Toys 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://ecs.amazonaws.com/onca/xml?
Service=AWSECommerceService&
AWSAccessKeyId=[AWS Access Key ID]&
Operation=ItemSearch&
Keywords=Mustang&
SearchIndex=Blended
Use the Availability parameter to only return shirts that are available:
http://ecs.amazonaws.com/onca/xml?
Service=AWSECommerceService&
AWSAccessKeyId=[AWS Access Key ID]&
Operation=ItemSearch&
MerchantId=All&
Condition=All&
Availability=Available&
SearchIndex=Apparel&
Keywords=Shirt
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> <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=B00021HBN6%2526tag=ws%2526lcode=xm2%2526cID=2025%2526ccmID=165953%2526location=/o/ASIN/B00021HBN6%25253FAWSAccessKeyId=[AWS Access Key ID]</DetailPageURL> <ItemAttributes> <Manufacturer>Radio Flyer</Manufacturer> <ProductGroup>Toy</ProductGroup> <Title>Radio Flyer Retro Rocket</Title> </ItemAttributes> </Item> <Item> <ASIN>B0007MZV3C</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=B0007MZV3C%2526tag=ws%2526lcode=xm2%2526cID=2025%2526ccmID=165953%2526location=/o/ASIN/B0007MZV3C%25253FAWSAccessKeyId=[AWS Access Key ID]</DetailPageURL> <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 ten results on a page.
