The ItemSearch operation enables you to search for products for a given search index or combination (blend) of search indices. This operation automatically corrects misspelled search words and displays the corrected word used in the search. In a blended search, the operation corrects the mispelled word in each SearchIndex. For example, if “propine” is the search word, “provine” might be used as the search word in the DVD index, and “profane” might be used in the Music index. The following shows the tags used in the spelling correction:
<CorrectedQuery> <Keywords>matrix</Keywords> <Message>We found no matches for matrx. Below are results for matrix.</Message> </CorrectedQuery>
Not all of the request parameters are compatible with all of the valid search indexes. To verify that your request is valid, check the search index matrix before submitting your request. Checking to see if your ItemSearch parameter combination is valid by using the Validate parameter in your request will be insufficient. Check the Search Index / Parameter Combinations page.
Note:
The list of all available search indexes by locale can be found on the search indexes page.
ItemSearch can search through a specified search index, or SearchIndex can be set to "Blended." A blended search includes the following search indices:
Books
Music
DVD
Toys
Video Games
Software
Software Video Games
Electronics
Tools
Sporting Goods
Art Supplies
Kitchen
Gourmet Food
Apparel
PC Hardware
VHS
ItemSearch is available in all of the locales.
Using ItemSearch (REST)
The following ItemSearch example demonstrates a keyword search within a specified index. It also returns the search results in the order specified by the sort that is entered.
http://webservices.amazon.com/onca/xml?Service=AWSECommerceService &AWSAccessKeyId=[Your Access Key ID Here] &Operation=ItemSearch&Keywords=[A Keywords String] &SearchIndex=[A Search Index String] &Sort=[A Sort String]
Request parameters specify the terms of your request and control the output data that is returned to you.
You must include the required parameters in every request.
ItemSearch accepts the optional parameters that are common to all operations:
The following parameters are specific to the ItemSearch operation:
| Parameter | Description | Required? | Value |
|---|---|---|---|
| Operation |
The operation |
Always Required | ItemSearch |
| Availability |
The Availability parameter enables ItemSearch to return only those items that are available. This parameter must be used in combination with MerchantId and Condition. For more information, see the discussion below this table. |
Optional |
Valid Values: Available |
| ReviewSort |
Specifies the order in which Reviews are sorted in the return. . |
Always Optional |
Default Value:
Valid Values:
|
| SearchIndex |
The Amazon store you want products from. The list of available SearchIndex values, listed by locale, can be found on the search index values page. |
Always Required |
Valid Values:
|
| Keywords |
Use the Keywords parameter to refine your item search based on specific words or phrases. Amazone E-Commerce Service (ECS) will match the word or phrase you include in your request against various product fields, including product title, author, artist, description, manufacturer, etc. When SearchIndex equals MusicTracks, the Keyword parameter enables you to search by song title. |
Valid Value:
|
|
| Title |
Use the Title parameter when you want to query against product titles only. You may use all or part of a title in your query. |
Valid Value:
|
|
| Power |
Use the Power parameter to perform book searches using a complex query string. For example the query "author:ambrose" returns a list of books that include "Ambrose" in the author name. A query of "subject:history and (spain or mexico) and not military and language:spanish" would return a list of books in the Spanish language on the subject of either Spanish or Mexican history, excluding all items with military in their subject. Query keys that may be used to build power queries include: asin, author, author-exact, author-begins, keywords, keywords-begin, language, publisher, subject, subject-words-begin, subject-begins, title, title-words-begin, and title-begins. The Power parameter can only be used with a book-related SearchIndex. In the US locale, the only valid SearchIndex value is "books." In other locales, the valid value for the index is of the form: books-locale-intl-us. For example, "books-de-intl-us," "books-fr-intl-us," "and "books-jp-intl-us." |
Valid Value:
|
|
| BrowseNode |
Use the BrowseNode parameter to narrow your search to a specific category of products in the Amazon catalog. The BrowseNode parameter may contain the ID of any Amazon browse node. For a list of Amazon browse nodes, please see Browse Node Values.
Please note that not all Amazon browse nodes have products classified under them. If you use such a browse node in your request, it will yield a |
Valid Value:
|
|
| Artist |
Use the Artist parameter refine your search by artist name. You may use all or part of an artist's name in your query. |
Valid Value:
|
|
| Author |
Use the Author parameter to refine your search by author name. You may use all or part of an author's name in your query. |
Valid Value:
|
|
| Actor |
Use the Actor parameter to refine your search by actor name. You may use all or part of an actor's name in your query. |
Valid Value:
|
|
| Director |
Use the Director parameter to refine your search by Director name. You may use all or part of a director's name in your query. |
Valid Value:
|
|
| AudienceRating |
Use the AudienceRating parameter to filter movie product search results by the expected audience maturity level. Amazon.com values are based upon MPAA (Motion Picture Association of America) ratings. Amazon.de values are based upon age. You may specify one or more values in a comma-separated list in a REST request or using multiple elements in a SOAP request. |
Valid Amazon.com Values:
Valid Amazon.de Values
Valid Amazon.fr Values
Valid Amazon.ca Values
|
|
| Manufacturer |
Use the Manufacturer parameter to refine your search by manufacturer name. You may use all or part of a manufacturer's name in your query. |
Valid Value:
|
|
| MusicLabel |
Use the MusicLabel parameter to refine your search by the record label name. You may use all or part of a record label's name in your query. |
Valid Values:
|
|
| Composer |
Use the Composer parameter to refine your search by composer name. You may use all or part of a composer's name in your query. |
Valid Values:
|
|
| Publisher |
Use the Publisher parameter to refine your search by publisher name. You may use all or part of a publisher's name in your query. |
Valid Value:
|
|
| Brand |
Use the Brand parameter to refine your search by brand name. You may use all or part of a brand's name in your query. |
Valid Value:
|
|
| Conductor |
Use the Conductor parameter to refine your search by conductor name. You may use all or part of a conductor's name in your query. |
Valid Value:
|
|
| Orchestra |
Use the Orchestra parameter to refine your search by orchestra name. You may use all or part of an orchestra's name in your query. |
Valid Value:
|
|
| TextStream |
In the US locale only, use the TextStream parameter to retrieve product search results based on a block of text you specify in your request. The text block could be a search term, a paragraph from a blog, an article excerpt, or any other text for which you wish to retrieve product matches. Amazon parses out recognized keywords and returns an equal number of products (ten total) for each recognized keyword. For example, if you send a request with five recognized keywords, Amazon will return two products matching each recognized keyword. The ItemPage parameter does not work when this parameter is being used--only one page can be returned. |
Valid Value:
|
|
| ItemPage |
ItemSearch returns up to ten search results at a time. The ItemPage parameter enables you to 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. |
Always Optional |
Default Value:
Valid Values:
|
| Sort |
Use the Sort parameter to specify how your item search results will be ordered. Please note that valid sort values vary by search index and locale. The full list of sort options are available in Sort Values. |
Always Optional |
Valid Values:
|
| City |
Use the City parameter to refine your restaurant search by city name. You may use all or part of a city's name in your query. At the present time, ECS return restaurants for only select cities (see Valid Values). This parameter may be used only when SearchIndex equals Restaurant and is only applicable to US requests. |
Valid Values:
|
|
| Cuisine |
Use the Cuisine parameter to refine your restaurant search by cuisine name (i.e., Chinese, Italian, American, etc.). You may use all or part of a cuisine's name in your query. This parameter may be used only when SearchIndex equals Restaurant and is only applicable to US requests. |
Valid Value:
|
|
| Neighborhood |
Use the Neighborhood parameter to refine your restaurant search by neighborhood name (i.e., Capitol Hill, Arlington, North Beach, etc.). You may use all or part of a neighborhood's name in your query. This parameter may be used only when SearchIndex equals Restaurant and is only applicable to US requests. |
Valid Value:
|
|
| MinimumPrice |
Use the MinimumPrice parameter to set a lower price bound on products returned by ItemSearch. The MinimumPrice value must be specified in pennies (or equivalent in local currency). |
Always Optional |
Valid Value:
|
| MaximumPrice |
Use the MaximumPrice parameter to set an upper price bound on products returned by ItemSearch. The MaximumPrice value must be specified in pennies (or equivalent in local currency). |
Always Optional |
Valid Value:
|
| MerchantId |
Filter the list of offerings returned by ItemSearch by the merchant offering the product. If not specified, Amazon is assumed to be the merchant for all requests. Setting MerchantId to "All" returns pricing information for Amazon and all other vendors. US only: You may also use the value "Featured," in which case ECS returns the same merchant that is displayed when you click the "Add to Shopping Cart" button on the product detail page. US only: MerchantId must be used with the response groups Variations, VariationMinimum, and/or VariationSummary. |
Optional |
Valid Amazon.com Values:
|
| 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." 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. |
Always Optional |
Default Value
Valid Values
|
| DeliveryMethod |
Use the DeliveryMethod parameter to filter offers returned in the product list by delivery method. Valid values are Ship and ISPU (In-store pickup). If you use ISPU, the offers returned will be ISPU offers from any postal code. To get ISPU offers from a specific postal code, you must use the ItemLookup operation. US only. |
Always Optional |
Default Value
Valid Values
|
| ResponseGroup |
Controls the data returned by the operation. Use this parameter to specify which response group(s), or group(s) of data elements, you would like ECS to return to you. You can specify as many response groups as you wish using a comma-separated list (REST) or multiple elements (SOAP). |
Always Optional |
Default Values Valid Values |
The Availability parameter filters out of ItemSearch results most of the items that are unavailable. The availability of an item sold by merchants and sellers 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:
Curently 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
The availability of an item can change rapidly. There is typically a lag time between an item’s availability as reported by ItemSearch, and an 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. These differences are most evident for items, such as software, whose availability changes often.
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.
Condition—Must be set to “All”.
MerchantId—Alphanumeric token that uniquely identifies a merchant. Valid values are “Amazon,” “All,” or a specific merchant ID.
Wnen 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:
Blended
Restaurants
The following ItemSearch request returns shirts that are available:
http://webservices.amazon.com/onca/xml? Service=AWSECommerceService& AWSAccessKeyId=[Your Access Key ID Here]& Operation=ItemSearch& MerchantId=All& Condition=All& Availability=Available& SearchIndex=Apparel& Keywords=Shirt
When you use ItemSearch and the Availability parameter is not used, and MerchantId is set to the string, “Amazon,” ItemSearch returns items sold by Amazon and all merchants and sellers. This is a known problem. Setting the Availability parameter to “Available,” however, makes ItemSearch correctly return available items sold only by Amazon.