Prev Next

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.

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

ParameterDefinitionReq'd?Valid Values
Actor Name of an actor associated with the item. You can enter all or part of the name.No String
Artist Name of an artist associated with the item. You can enter all or part of the name. No String
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. No String. For a list of valid values, see Movie Ratings by Locale, which follows this table.
Author Name of an author associated with the item. You can enter all or part of the name.No String
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."Yes Available
Brand Name of a brand associated with the item. You can enter all or part of the name.No String, for example, Timex, Seiko, Rolex.
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).No Positive integer.
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.No

Chicago

New York

San Francisco

Seattle

Washington, D.C.

Composer Name of an composer associated with the item. You can enter all or part of the name.No String
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.

No

New (default)

Used

Collectible

Refurbished

All

Conductor Name of a conductor associated with the item. You can enter all or part of the name.No String
Director Name of a director associated with the item. You can enter all or part of the name.No String
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. No Integer between 1 and 400, inclusive.
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.No String
Manufacturer Name of a manufacturer associated with the item. You can enter all or part of the name.No String
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.No Positive integer
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."Yes

Amazon (default)

Valid merchant ID of a merchant

All--Includes Amazon and all other merchants

Featured--Merchant listed when you click “Add to Cart” (US only)

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.No Positive integer
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.No String, for example, Capitol Hill, Arlington, and North Beach.
Orchestra Name of an orchestra associated with the item. You can enter all or part of the name.No String
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. No String
Power Performs a book search using a complex query string. Only works when the search index is set equal to "Books."No See, Power Searches below this table.
Publisher Name of a publisher associated with the item. You can enter all or part of the name.No String
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.No 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
Sort Means by which the items in the response are ordered. No Valid values vary significantly by search index. For a list of valid values, see ItemSearch Sort Values by Locale.
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.No String
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.No String
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.No Positive integer
ResponseGroup Specifies the types of values to return. You can specify multiple response groups in one request by separating them with commas.No

Request (Default)

Small (Default)

Accessories

BrowseNodes

EditorialReview

ItemAttributes

ItemIds

Large

ListmaniaLists

Medium

MerchantItemAttributes

OfferFull

Offers

OfferSummary

Reviews

SalesRank

SearchBins

Similarities

Subjects

Tracks

VariationMinimum

Variations

VariationSummary

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:

You cannot use the All search index in an ItemLookup request.

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

ItemSearch automatically corrects misspelled keywords and displays the corrected word used in the search. In a "blended" and "all" search, the operation corrects the mispelled word in each search index. For example, if “propine” is entered in the request as the Keywords value, “provine” might be used as the keyword in the DVD index, and “profane” might be used in the Music index. The following example shows a snippet of an XML response in which the spelling of the Keywords value was corrected..

<CorrectedQuery>
  <Keywords>matrix</Keywords>
  <Message>We found no matches for matrx. Below are results for matrix.</Message>
</CorrectedQuery>

Spelling correction is not supported in all search indices. For more information, see "Automatic Spelling Correction."

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

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

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

ParameterValid 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 TagDefinition
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:

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

Prev Copyright Information Next