ItemSearch

Product Advertising API: 2009-11-01

previous page next page

ItemSearch

Description

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

Name	Description	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. 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." Type: String 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. Type: String 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). Type: String 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. Type: String 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. Type: String 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. Type: String 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. Type: String 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." Type: String 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. Type: String 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. Type: String 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 following this table. Type: String 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
`RelatedItemsPage`	This optional parameter is only valid when the `RelatedItems` response group is used. Each `ItemLookup` request can return, at most, ten related items. The RelatedItemsPage value specifies the set of ten related items to return. A value of 2, for example, returns the second set of ten related items.	No
`RelationshipType`	This parameter is required when the `RelatedItems` response group is used. The type of related item returned is specified by the `RelationshipType` parameter. Sample values include Episode, Season, and Tracks. A complete list of values follows this table. Constraint: Required when RelatedItems response group is used	Conditional
ReviewSort	Sorts reviews based on the value of the parameter. Type: String Default: None Valid Values: -HelpfulVotes, HelpfulVotes, -OverallRating, OverallRating, Rank, -Rank, -SubmissionDate, SubmissionDate	No
`SearchIndex`	The product category to search. Many `ItemSearch` parameters are valid with only specific values of `SearchIndex`. Type: String Default: None Valid Values: A search index, for example, Apparel, Beauty, Blended, Books, and so forth. For Blended searches, go to Blended Searches. For a complete of search indices, see Search Indices by Locale.	No
`Sort`	Means by which the items in the response are ordered. Type: String 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 Type: String Default: None	No
`TagsPerPage`	The number of tags to return that are associated with a specified item. Type: Integer Type: String Default: None	No
`TagSort`	Specifies the sorting order for the results. Type: String 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 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. Type: String 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. Type: String Default: Small Valid Values: Accessories \| BrowseNodes \| EditorialReview \| ItemAttributes \| ItemIds \| Large \| ListmaniaLists \| Medium \| MerchantItemAttributes \| OfferFull \| Offers \| OfferSummary \| Reviews \| RelatedItems \| 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

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

Response

Name	Description
`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.

Examples

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.

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.

Sample Response

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

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

Related Operations

previous page start next page