An ItemSearch operation in Amazon E-Commerce Service (ECS) uses keywords or other criteria to search for products or restaurants. The ItemSearch operation combines several of the searches from Amazon Web Services 3.0, including KeywordSearch, PowerSearch, BrowseNodeSearch, AuthorSearch, ArtistSearch, ActorSearch, DirectorSearch, ManufacturerSearch, BlendedSearch, and TextStreamSearch.
Setting up an ItemSearch operation consists of three steps:
There are only two required parameters to the ItemSearch operation:
| Parameter | Value |
|---|---|
| Operation | ItemSearch |
| SearchIndex | The name of an Amazon store index for searching. The indexes available vary by locale. |
In addition to specifying the store to search, you must also specify search parameters, as described below.
Note that some of the search indexes are actually composites:
Video combines DVD and VHS
Music combines Classical, DigitalMusic, MusicTracks
Blended combines 12 useful search indexes: DVD Electronics Toys VideoGames PCHardware Tools SportingGoods Books Software Music GourmetFood Kitchen Apparel .
Once you have specified the store to search, you must narrow your search in some way, by requesting certain types of content or product attributes. The search parameter options are:
There are several ways to use the ItemSearch operation to search for products, by the products' subject or content, as shown in the table below.
| Parameter | Description |
|---|---|
| Keywords | ECS will match this word or phrase against various product fields, including product title, author, artist, description, manufacturer, etc. |
| Title | All or part of the name of the product. |
| TextStream | US only. Retrieve products 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. When Amazon receives your request, 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. |
| BrowseNodes | Product category. |
The ItemSearch operation can be used to search for the creator or performer of the product or the product's owner/producer.
| Parameter | Description |
|---|---|
| Artist | All or part of artist's name. |
| Author | All or part of author's name. |
| Actor | All or part of actor's name. |
| Director | All or part of director's name. |
| Composer | All or part of composer's name. |
| Conductor | All or part of conductor's name. |
| Orchestra | All or part of orchestra name. |
| MusicLabel | All or part of record label name. |
| Publisher | All or part of publisher's name. |
The ItemSearch operation can also be used to search by manufacturer or brand.
| Parameter | Description |
|---|---|
| Manufacturer | All or part of manufacturer's name. |
| Brand | All or part of brand name. |
Use the Power parameter to perform book searches on Amazon using a complex query string. Complex query strings are of the format:
key:value
where keys 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.
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.
A sample REST request might thus be:
http://webservices.amazon.com/onca/xml?Service=AWSECommerceService &SubscriptionId=[ID] &Operation=ItemSearch &SearchIndex=Books &Power=subject:history%20and%20language:spanish
Note that for REST, any spaces in your power search query string must be URL-encoded as in the example above.
The Power parameter can only be used when SearchIndex equals Books. Go to the PowerSearch tool online at the Amazon Web site for more information about Power search.
You can search the Video, DVD or VHS search indexes using the AudienceRating parameter. This parameter contains country-specific ratings about the age appropriateness of movies.
US: Based on the Motion Picture Association of America (MPAA) ratings, values are G, PG, PG-13, R, NR or unrated.
DE: Based on age, values are: 6, 12 or 16.
You may specify one or more values in a comma-separated list in a REST request or using multiple elements in a SOAP request.
There are three search parameters that work with the Restaurants search index, listed in the table below.
| Parameter | Description |
|---|---|
| Cuisine | Type of food prepared by a restaurant. Can be ethnic types such as Greek, Japanese, Italian. Can also be food types like Seafood. |
| City | City where the restaurant is located. Valid values are Seattle, Boston, Chicago, New York, San Francisco, San Diego. |
| Neighborhood | Neighborhood within the city where the restaurant is located. These are both general areas such as Waterfront or Downtown as well as city-specific neighborhoods such as Phinney Ridge (in Seattle). |
There are three parameters to the ItemSearch operation that allow you to search for products by price and condition, as shown in the table below.
| Parameter | Description |
|---|---|
| MinimumPrice | Return only products that are higher than this minimum price. The MinimumPrice value must be specified in cents (US, DE), pence (UK), or yen (JP). |
| MaximumPrice | Return only products that are lower than this maximum price. The MaximumPrice value must be specified in cents (US, DE), pence (UK), or yen (JP). |
| Condition | All, New, Used, Refurbished, or Collectible. |
For large Amazon partners with merchant IDs, you can search for products by merchant ID or by shipping method as shown in the table below.
| Parameter | Description |
|---|---|
| MerchantId | ID of merchant selling the product. |
| DeliveryMethod | Ship or ISPU (in-store pickup). |
Not all search parameters can be combined. Valid combinations depend on the search index chosen. You can verify that your desired search combination is valid by checking the search index matrix.
You can manage the data returned by ECS in several ways:
You can change the default order of the items in the response by including the Sort parameter in your ItemSearch request. Valid sort values vary by search index and by locale.
By default, ECS returns a standard set of XML data. You can specify an XSL stylesheet for returned data.
Each ItemSearch operation returns up to ten product listings. You can use the ItemPage parameter to retrieve additional pages of ten listings, up to 3200 pages.
You can page through products with the ItemPage parameter as shown in the table below.
| Parameter | Default Page Number | Items per page | Valid Values | Description |
|---|---|---|---|---|
| ItemPage | 1 | 10 | 1..3200 | Products. Up to 3200 pages of products can be returned (10 per page). |
All ECS operations support the ResponseGroup parameter which specifies the data subset to be returned. Since Item elements are returned by ItemSearch, the response groups are similar to the response groups for ItemLookup. Valid response groups for ItemSearch are listed below. If no response groups are specified in an ItemSearch operation, the default is Request and Small.
Standard response groups:
Amalgamated response groups:
Small - Global, item-level data (no pricing or availability), including the ASIN, product title, creator (author, artist, composer, directory, manufacturer, etc.), product group, URL, and manufacturer.
Medium - Includes Small, Request, ItemAttributes, OfferSummary, SalesRank, EditorialReview, and Images response groups.
Large - Includes Medium, Tracks, BrowseNodes, Reviews, ListmaniaLists, Similarities, Offers, and Accessories response groups.
Offer information (actual prices/availability):
Offers - Includes OfferSummary plus all offer listings specified by the Condition parameter
OfferFull - Includes Offers plus merchant name or seller nickname.
Variations data management:
Various product attributes:
You want to locate cover art for the videos (either VHS or DVD) for the Harry Potter movies. Your REST request might look like this:
http://webservices.amazon.com/onca/xml?Service=AWSECommerceService &SubscriptionId=[ID] &Operation=ItemSearch &SearchIndex=Video &Keywords=potter%20harry &ResponseGroup=Images
If you wanted only the DVD cover art, you would instead use the request:
http://webservices.amazon.com/onca/xml?Service=AWSECommerceService &SubscriptionId=[ID] &Operation=ItemSearch &SearchIndex=DVD &Keywords=potter%20harry &ResponseGroup=Images
You want to find CDs that contain music by Beethoven. Your REST request might look like this:
http://webservices.amazon.com/onca/xml?Service=AWSECommerceService &SubscriptionId=[ID] &Operation=ItemSearch &SearchIndex=Music &ResponseGroup=Small,Tracks &Composer=Beethoven
As a vendor, you want to search for all of your own product listings in the Apparel store, to verify their accuracy. You therefore want to view all of the available data (including variations). Your REST requests would look like this:
http://webservices.amazon.com/onca/xml?Service=AWSECommerceService &SubscriptionId=[ID] &Operation=ItemSearch &SearchIndex=Apparel &ResponseGroup=Large,Variations &MerchantId=[ID] &ItemPage=1 http://webservices.amazon.com/onca/xml?Service=AWSECommerceService &SubscriptionId=[ID] &Operation=ItemSearch &SearchIndex=Apparel &ResponseGroup=Large,Variations &MerchantId=[ID] &ItemPage=2
You want to find all products on Amazon that cost less than $1.00. Your REST request would look like this:
http://webservices.amazon.com/onca/xml?Service=AWSECommerceService &SubscriptionId=[ID] &Operation=ItemSearch &SearchIndex=Blended &ResponseGroup=Small,Offers &MerchantId=All &MaximumPrice=99
Note that this would return only New products. For both new and used products, you would use the request:
http://webservices.amazon.com/onca/xml?Service=AWSECommerceService &SubscriptionId=[ID] &Operation=ItemSearch &SearchIndex=Blended &ResponseGroup=Small,Offers &MerchantId=All &MaximumPrice=99 &Condition=All
You visit Seattle and want to find seafood restaurants near your downtown hotel. Your REST request might look like this:
http://webservices.amazon.com/onca/xml?Service=AWSECommerceService &SubscriptionId=[ID] &Operation=ItemSearch &SearchIndex=Restaurants &Cuisine=seafood &Neighborhood=downtown &City=Seattle
You are considering opening a used Barbie doll merchandise store and you want to find out what products are available through Amazon. Your REST requests might look like this:
http://webservices.amazon.com/onca/xml?Service=AWSECommerceService &SubscriptionId=[ID] &Operation=ItemSearch &SearchIndex=Toys &Title=Barbie &Manufacturer=Mattel &Condition=All &ItemPage=1 http://webservices.amazon.com/onca/xml?Service=AWSECommerceService &SubscriptionId=[ID] &Operation=ItemSearch &SearchIndex=Toys &Title=Barbie &Manufacturer=Mattel &Condition=All &ItemPage=2
Your doctor tells you that you are allergic to milk chocolate, so you want to search for Godiva dark chocolate products. Your REST request would look like this:
http://webservices.amazon.com/onca/xml?Service=AWSECommerceService &SubscriptionId=[ID] &Operation=ItemSearch &SearchIndex=GourmetFood &Keywords=dark%20chocolate &Manufacturer=Godiva
Your daughter announces that she will not have anything to do with anything that is not purple, so you decide to build her a Web site that features only purple products. Your REST request might look like this:
http://webservices.amazon.com/onca/xml?Service=AWSECommerceService &SubscriptionId=[ID] &Operation=ItemSearch &SearchIndex=Blended &Keywords=purple
The UK site permits lookups similar to the US site with the following differences:
You want to locate cover art for the videos (either VHS or DVD) for the Harry Potter movies. Your REST request might look like this:
http://webservices.amazon.co.uk/onca/xml?Service=AWSECommerceService &SubscriptionId=[ID] &Operation=ItemSearch &SearchIndex=Video &Keywords=potter%20harry &ResponseGroup=Images
If you wanted only the DVD cover art, you would instead use the request:
http://webservices.amazon.co.uk/onca/xml?Service=AWSECommerceService &SubscriptionId=[ID] &Operation=ItemSearch &SearchIndex=DVD &Keywords=potter%20harry &ResponseGroup=Images
You want to find CDs that contain music by Beethoven. Your REST request might look like this:
http://webservices.amazon.co.uk/onca/xml?Service=AWSECommerceService &SubscriptionId=[ID] &Operation=ItemSearch &SearchIndex=Music &ResponseGroup=Small,Tracks &Composer=Beethoven
You want to find all products on Amazon that cost less than one pound. Your REST request would look like this:
http://webservices.amazon.co.uk/onca/xml?Service=AWSECommerceService &SubscriptionId=[ID] &Operation=ItemSearch &SearchIndex=Blended &ResponseGroup=Small,Offers &MerchantId=All &MaximumPrice=99
Note that this would return only New products. For both new and used products, you would use the request:
http://webservices.amazon.co.uk/onca/xml?Service=AWSECommerceService &SubscriptionId=[ID] &Operation=ItemSearch &SearchIndex=Blended &ResponseGroup=Small,Offers &MerchantId=All &MaximumPrice=99 &Condition=All
You are considering opening a used Barbie doll merchandise store and you want to find out what products are available through Amazon. Your REST requests might look like this:
http://webservices.amazon.co.uk/onca/xml?Service=AWSECommerceService &SubscriptionId=[ID] &Operation=ItemSearch &SearchIndex=Toys &Title=Barbie &Manufacturer=Mattel &Condition=All &ItemPage=1 http://webservices.amazon.co.uk/onca/xml?Service=AWSECommerceService &SubscriptionId=[ID] &Operation=ItemSearch &SearchIndex=Toys &Title=Barbie &Manufacturer=Mattel &Condition=All &ItemPage=2
Your daughter announces that she will not have anything to do with anything that is not purple, so you decide to build her a Web site that features only purple products. Your REST request might look like this:
http://webservices.amazon.co.uk/onca/xml?Service=AWSECommerceService &SubscriptionId=[ID] &Operation=ItemSearch &SearchIndex=Blended &Keywords=purple
The DE site permits searches similar to the US site with the following differences:
You want to find all videos (new and used) suitable for children 6 and under, with a price not exceeding 10 euros. Your REST request might look like this:
http://webservices.amazon.de/onca/xml?Service=AWSECommerceService &SubscriptionId=[ID] &Operation=ItemSearch &SearchIndex=Video &ResponseGroup=Small,Offers &MerchantId=All &MaximumPrice=1000 &AudienceRating=6 &Condition=All
You want to locate cover art for the videos (either VHS or DVD) for the Harry Potter movies. Your REST request might look like this:
http://webservices.amazon.de/onca/xml?Service=AWSECommerceService &SubscriptionId=[ID] &Operation=ItemSearch &SearchIndex=Video &Keywords=potter%20harry &ResponseGroup=Images
If you wanted only the DVD cover art, you would instead use the request:
http://webservices.amazon.de/onca/xml?Service=AWSECommerceService &SubscriptionId=[ID] &Operation=ItemSearch &SearchIndex=DVD &Keywords=potter%20harry &ResponseGroup=Images
You want to find CDs that contain music by Beethoven. Your REST request might look like this:
http://webservices.amazon.de/onca/xml?Service=AWSECommerceService &SubscriptionId=[ID] &Operation=ItemSearch &SearchIndex=Music &ResponseGroup=Small,Tracks &Composer=Beethoven
You want to find all products on Amazon that cost less than one euro. Your REST request would look like this:
http://webservices.amazon.de/onca/xml?Service=AWSECommerceService &SubscriptionId=[ID] &Operation=ItemSearch &SearchIndex=Blended &ResponseGroup=Small,Offers &MerchantId=All &MaximumPrice=99
Note that this would return only New products. For both new and used products, you would use the request:
http://webservices.amazon.de/onca/xml?Service=AWSECommerceService &SubscriptionId=[ID] &Operation=ItemSearch &SearchIndex=Blended &ResponseGroup=Small,Offers &MerchantId=All &MaximumPrice=99 &Condition=All
Your daughter announces that she will not have anything to do with anything that is not purple, so you decide to build her a Web site that features only purple products. Your REST request might look like this:
http://webservices.amazon.de/onca/xml?Service=AWSECommerceService &SubscriptionId=[ID] &Operation=ItemSearch &SearchIndex=Blended &Keywords=purple
The JP site permits searches similar to the US site with the following differences:
You want to locate cover art for the videos (either VHS or DVD) for the Harry Potter movies. Your REST request might look like this:
http://webservices.amazon.co.jp/onca/xml?Service=AWSECommerceService &SubscriptionId=[ID] &Operation=ItemSearch &SearchIndex=Video &Keywords=potter%20harry &ResponseGroup=Images
If you wanted only the DVD cover art, you would instead use the request:
http://webservices.amazon.co.jp/onca/xml?Service=AWSECommerceService &SubscriptionId=[ID] &Operation=ItemSearch &SearchIndex=DVD &Keywords=potter%20harry &ResponseGroup=Images
You want to find CDs that contain music by Beethoven. Your REST request might look like this:
http://webservices.amazon.co.jp/onca/xml?Service=AWSECommerceService &SubscriptionId=[ID] &Operation=ItemSearch &SearchIndex=Music &ResponseGroup=Small,Tracks &Composer=Beethoven
You want to find all products on Amazon that cost less than 100 yen. Your REST request would look like this:
http://webservices.amazon.co.jp/onca/xml?Service=AWSECommerceService &SubscriptionId=[ID] &Operation=ItemSearch &SearchIndex=Blended &ResponseGroup=Small,Offers &MerchantId=All &MaximumPrice=99
Note that this would return only New products. For both new and used products, you would use the request:
http://webservices.amazon.co.jp/onca/xml?Service=AWSECommerceService &SubscriptionId=[ID] &Operation=ItemSearch &SearchIndex=Blended &ResponseGroup=Small,Offers &MerchantId=All &MaximumPrice=99 &Condition=All
Your daughter announces that she will not have anything to do with anything that is not purple, so you decide to build her a Web site that features only purple products. Your REST request might look like this:
http://webservices.amazon.co.jp/onca/xml?Service=AWSECommerceService &SubscriptionId=[ID] &Operation=ItemSearch &SearchIndex=Blended &Keywords=purple
ItemSearch returns data similar to ItemLookup and ListLookup. If you don't get the returned data that you expect, the most common culprit is a response group that does not include the data you require.
If you are attempting to find out if a product can be purchased, you must be sure to include the appropriate response group (Offers, OfferSummary or OfferFull).
For debugging purposes, no single response group returns all of the data. However for ItemSearch, setting the ResponseGroup parameter to include Large and Variations (US only) will return all available data. This may result in a very large response, but for debugging, it's an ideal way to look at all of the available data.