ItemSearch

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.

Availability

All locales.

Request Parameters

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:

Actor
Artist
AudienceRating
Author
Brand
BrowseNode
City

Composer
Conductor
Director
Keywords
Manufacturer
MusicLabel
Neighborhood

Orchestra
Power
Publisher
TextStream
Title

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 `ItemSearch` to return only those items that are available. This parameter must be used in combination with a merchant ID and `Condition`. For more information, see Availability Parameter, which follows this table.When Availability is set to "Available," the Condition parameter cannot be set to "New." 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 `Condition` parameter to filter the offers returned in the product list by condition type. By default, `Condition` equals "New". If you do not get results, consider changing the value to "All. When the Availability parameter is set to "Available," the Condition parameter cannot be set to "New." `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. 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 `Condition` equals "All." In that case, `ItemSearch` returns up to three results per `Condition`, for example, three new, three used, three refurbished, and three collectible items. Or, for example, if there are no collectible or refurbished items being offered, `ItemSearch` returns three new and three used items. 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. The total number of pages of items found is returned in the `TotalPages` response tag. 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 `Keywords` parameter enables you to search by song title. If you enter a phrase, the spaces must be URL-encoded as %20. 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. `MerchantId` is an alphanumeric identifier assigned by Amazon to merchants. Make sure to specify a merchant ID and not a seller ID, which is not supported. Note that the default value is "Amazon." If your request does not generate results, consider setting the value to "All." 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 `City`. 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 below 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 `ItemSearch` parameters are valid with only specific values of `SearchIndex`. For more information, see Search Indices and Valid Parameter Values below this table. 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: FirstUsed-Sort by the date the item was first used. - FirstUsed LastUsed-Sort by the date the item was last used. - LastUsed Name-Alphabetical, A-Z. - Name Usages-Items least used to most used To sort items in descending order, prefix the above values with a negative sign (-).	No
`TextStream`	A search based on two or more words. `ItemSearch` picks out of the block of text up to ten keywords and returns up to ten items that match those keywords. For example, if five keywords are found, two items for each keyword are returned. Only one page of results is returned so `ItemPage` does not work with `TextStream`. Type: String Default: None	No
`Title`	The title associated with the item. You can enter all or part of the title. `Title` searches are a subset of `Keyword` searches. If a `Title` search yields insufficient results, consider using a `Keywords` search. Type: String Default: None	No
`VariationPage`	Retrieves a specific page of variations returned by `ItemSearch`. By default, `ItemSearch` 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. The total number of pages is returned in the `TotalPages` element. 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

All Search Index

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
	You cannot use the All search index in an `ItemLookup` request.

Blended Searches

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

Apparel
Automotive
Books
DVD
Electronics
GourmetFood

Kitchen
Music
PCHardware
PetSupplies
Software
SoftwareVideoGames

SportingGoods
Tools
Toys
VHS
VideoGames

Availability Parameter

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:

Currently for sale
Pre-orders
Special orders
New releases
e-mail me when items become available
Items available for in-store pickup
Items for sale by third parties

Parameter Restrictions for Availability

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 Ratings Vary by Locale

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

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

Power Search Key Words

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 Syntax

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.

Search Indices and Valid Parameter Values

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

Response Tags

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.

Sample Requests

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, below.
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.

Response to Sample Request

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

<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.