The ItemSearch operation allows you to search for products and restaurants. It replaces operations from previous versions of the service, including KeywordSearch, PowerSearch, BrowseNodeSearch, AuthorSearch, ArtistSearch, ActorSearch, DirectorSearch, ManufacturerSearch, BlendedSearch, and TextStreamSearch.
Note:
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 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&SubscriptionId=[Your Subscription 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 |
| 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 allows 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 when SearchIndex equals Books. Please see this page on Amazon for more information about power search: http://www. amazon.com/exec/obidos/ats-query-page#powersearch. |
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 |
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 |
The ItemPage parameter allows you to create a paginated list of search results. This parameter returns the specified page. When you use ItemPage, ItemSearch will return 10 search results at a time. The maximum ItemPage number that can be returned is 2500. If you do not include ItemPage in your request, the first page (containing the first 10 items, or all of the items if there are less than 10) 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, a request with the Condition parameter will return a maximum of 10 offers, with a maximum of 5 offer listings per offer. |
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 |