Product Advertising API
Developer Guide (API Version 2013-08-01)
Did this page help you?  Yes | No |  Tell us about it...
« PreviousNext »
View the PDF for this guide.Go to the AWS Discussion Forum for this product.

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 per page. When condition equals "All," ItemSearch returns additional offers for those items, one offer per condition type (if an offer exists)—for example, one new, one used, one refurbished, and one collectible item. Or, for example, if there are no collectible or refurbished offers, ItemSearch returns one new and one used offer.

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

For more discussion about finding items by BrowseNode, see Understanding BrowseNode Results When Drilling Down.

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, see Locale Reference.

The parameters that apply to the largest number of search indices are shown in the following table.

ParameterValid Search Indices
BrowseNode Every index except All and Blended
Condition Every index except All and Blended
Keywords All
MaximumPrice Every index except All and Blended
MinimumPrice Every index except All and Blended
Title Every index except All and Blended

ItemSearch requires that you specify a search index and at least one of the following parameters:

  • Actor

  • Artist

  • AudienceRating

  • Author

  • Brand

  • BrowseNode

  • Composer

  • Conductor

  • Director

  • Keywords

  • Manufacturer

  • MusicLabel

  • Orchestra

  • Power

  • Publisher

  • Title

NameDescriptionRequired
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
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
IncludeReviewsSummary

When set to true, returns the reviews summary within the Reviews iframe.

Type: Boolean

Default: True

Valid Values: True | False

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 additional offers for those items, one offer per condition type (if an offer exists)—for example, one new, one used, one refurbished, and one collectible item. Or, for example, if there are no collectible or refurbished offers, ItemSearch returns one new and one used offer. If you do not include ItemPage in your request, the first page is returned. The total number of pages of items found is returned in the TotalPages response tag.

Valid Values: 1 to 10 (1 to 5 when the search index = "All")

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

An optional parameter you can use to filter search results and offer listings to only include items sold by Amazon. By default, Product Advertising API returns items sold by various merchants including Amazon. Use the Amazon to limit the response to only items sold by Amazon.

Type: String

Valid Values: Amazon

No
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
MinPercentageOff

Specifies the minimum percentage off for the items to return.

Type: String

Default: None

Valid Values: Positive integer

No
Orchestra

Name of an orchestra associated with the item. You can enter all or part of the name.

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
RelatedItemPage This optional parameter is only valid when the RelatedItems response group is used. Each ItemLookup request can return, at most, ten related items. The RelatedItemPage 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
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 list of search indices, see Locale Reference.

Yes
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 Locale Reference.

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
TruncateReviewsAt

By default, reviews are truncated to 1000 characters within the Reviews iframe. To specify a different length, enter the value. To return complete reviews, specify 0.

Type: Integer

Default: 1000

Constraints: Must be a positive integer or 0 (returns entire review)

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 | Medium | OfferFull | Offers | OfferSummary | Reviews | RelatedItems | SearchBins | Similarities | Small | Tracks | 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.

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

Response

NameDescription
ASIN Amazon Standard Identification Number, which is an alphanumeric token assigned by Amazon to an item that uniquely identifies it.
Item Container for item information, including ASIN and ItemAttributes.
ItemAttributes Container for information about an item, including Manufacturer, ProductGroup, and Title.
Manufacturer Item’s manufacturer.
MoreSearchResultsURL The URL where the complete search results are displayed. The URLs provided in the search results are the exact ones that you should use when you link back to Amazon.com. They are tagged with your Associate tag and contain other tracking information to increase your hourly request limit as the sales that you generate increase.
ProductGroup Product category; similar to search index.
Title Item’s title.
TotalPages Total number of pages in response. There are up to 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://webservices.amazon.com/onca/xml?
Service=AWSECommerceService&
AWSAccessKeyId=[AWS Access Key ID]&
Operation=ItemSearch&
Keywords=Rocket&
SearchIndex=Toys
&Timestamp=[YYYY-MM-DDThh:mm:ssZ]
&Signature=[Request Signature]

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://webservices.amazon.com/onca/xml?
Service=AWSECommerceService&
AWSAccessKeyId=[AWS Access Key ID]&
Operation=ItemSearch&
Keywords=Mustang&
SearchIndex=Blended
&Timestamp=[YYYY-MM-DDThh:mm:ssZ]
&Signature=[Request Signature]

Use the Availability parameter to only return shirts that are available:

http://webservices.amazon.com/onca/xml?
Service=AWSECommerceService&
AWSAccessKeyId=[AWS Access Key ID]&
Operation=ItemSearch&
Condition=All&
Availability=Available&
SearchIndex=Apparel&
Keywords=Shirt
&Timestamp=[YYYY-MM-DDThh:mm:ssZ]
&Signature=[Request Signature]

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>
  <ItemAttributes>
    <Manufacturer>Radio Flyer</Manufacturer>
    <ProductGroup>Toy</ProductGroup>
    <Title>Radio Flyer Retro Rocket</Title>
  </ItemAttributes>
  </Item>
  <Item>
  <ASIN>B0007MZV3C</ASIN>
  <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 up to ten results on a page.

Related Operations