Menu
Product Advertising API
Developer Guide (API Version 2013-08-01)

SearchBins

The SearchBins response group groups the items returned by ItemSearch into bins. For example, a set of bins can be a set of price ranges for a product. In the case of women’s shoes, you might have a bin that returns ASINs for shoes that cost between $0 and $50, a second bin for shoes that cost $50 to $100, and a third bin for shoes that cost more than $100. The basis on which the items are split into bins is specified by the NarrowBy attribute in the SearchBinSet tag. To refine the search, you make repeated requests using the NarrowBy values.

ItemSearch returns the first 25 bins of results.

For more information about search bins, see Using Search Bins to Find Items.

Availability

US locale only.

NarrowBy

The basis on which the items are split into bins is specified by the NarrowBy attribute in the SearchBinSet tag. In the following example, the NarrowBy attribute shows that the bins are based on price range:

Copy
<SearchBinSet NarrowBy="PriceRange">

For another product category, the NarrowBy attribute might be different, for example:

Copy
<SearchBinSet NarrowBy="BrandName">

You cannot specify NarrowBy values nor can you specify the values they encompass. When SearchBins is included as a Response Group in a request, ItemSearch automatically divides the ItemSearch results into bins.

NarrowBy Values

NarrowBy values include:

  • Subject—BrowseNode IDs of all topics related to items returned by ItemSearch. For example, searching for books about dogs returns, in the Subject bins, BrowseNodes for "Home & Garden," "Animal Care & Pets," "Dogs," and "Educational."

  • BrandName—Brands, such as Levi's, Reebok, and Nike, that create the item. Use the name of a brand to filter out similar items made by other companies.

  • PriceRange—Minimum and maximum prices for a bin of items. Use the minimum and maximum price values in each bin to filter out items outside of the price range you want.

  • PercentageOff—Percentage off required on items returned. Use the values returned with MinPercentageOff key to refine the results

All Search Indices return the Subject bin. Most return all of the bins.

NarrowBy Values by Search Index

The following list shows which NarrowBy values are returned by each Search Index:

  • Apparel—Subject, BrandName, PriceRange, PercentageOff

  • Appliances—Subject, BrandName, PriceRange, PercentageOff

  • ArtsAndCrafts—Subject, BrandName, PriceRange, PercentageOff

  • Automotive—Subject, BrandName, PriceRange, PercentageOff

  • Baby—Subject, BrandName, PriceRange, PercentageOff

  • Beauty—Subject, BrandName, PriceRange, PercentageOff

  • Blended—Not supported

  • Books—Subject

  • Classical—Subject

  • DigitalMusic—Subject

  • DVD—Subject

  • Electronics—Subject, BrandName, PriceRange

  • GourmetFood—Subject, BrandName, PriceRange

  • Grocery--Subject, BrandName, PriceRange

  • HealthPersonalCare—Subject, BrandName, PriceRange, PercentageOff

  • HomeGarden—Subject, BrandName, PriceRange, PercentageOff

  • Industrial—Subject, BrandName

  • Jewelry—Subject, PriceRange, PercentageOff

  • KindleStore—Subject

  • Kitchen—Subject, BrandName, PriceRange, PercentageOff

  • Magazines—Subject

  • Miscellaneous—BrandName, PriceRange, PercentageOff

  • MobileApps—Subject, PriceRange

  • MP3Downloads—Subject

  • Music—Subject

  • MusicalInstruments—Subject, BrandName, PriceRange, PercentageOff

  • MusicTracks—Subject

  • OfficeProducts—Subject, BrandName, PriceRange, PercentageOff

  • OutdoorLiving—Subject, BrandName, PriceRange, PercentageOff

  • PCHardware—Subject, BrandName, PriceRange

  • PetSupplies—Subject, BrandName, PriceRange, PercentageOff

  • Photo—Subject, BrandName, PriceRange

  • Shoes—Subject, BrandName, PriceRange, PercentageOff

  • Software—Subject, PriceRange, PercentageOff

  • SportingGoods—Subject, BrandName, PriceRange, PercentageOff

  • Tools—Subject, BrandName, PriceRange, PercentageOff

  • Toys—Subject, BrandName, PriceRange, PercentageOff

  • UnboxVideo—Subject, PriceRange

  • VHS—Subject

  • Video—Subject

  • VideoGames—Subject, BrandName, PriceRange

  • Watches—Subject, BrandName, PriceRange, PercentageOff

  • Wireless—Subject, PriceRange, PercentageOff

  • WirelessAccessories—Subject, PriceRange, PercentageOff

Element Tags in a Bin

The element tags in a bin vary according to the bin. For example, in bins based on price, the elements and Name values are:

Copy
<BinName> <BinItemCount> <BinParameter> <Name>MinimumPrice</Name> <Value> <BinParameter> <Name>MaximumPrice</Name> <Value>

The elements show the minimum and maximum price for items in that bin, and the number of items in that bin.

Other NarrowBy values use other element tags in their bins. For example, when NarrowBy is “Brand,” the element tags and Name values are:

Copy
<Bin> <BinName> <BinItemCount> <BinParameter> <Name>Brand</Name> <Value>

You cannot specify the element tags returned in a bin.

Drilling Down

You can take the values in a bin and add them to the ItemSearch query to filter out of the response items that are outside of that bin. To narrow the search results to shirts that cost between $0 and $25, for example, you would add the following Name and its corresponding value as additional parameters in the original ItemSearch request:

Copy
&MinimumPrice=0 &MaximumPrice=2499

You could narrow the search results even further by adding an additional parameter to the query. For example, you could specify

Copy
&Brand=Levi’s

The response would then only include shirts by Levi’s that cost under $25. You could continue to drill down by adding additional parameters to the request.

Notice that in each case the results were narrowed down by adding the value tagged with Name and its corresponding value to the original ItemSearch request.

Relevant Operations

Operations that can use this response group include:

Response Elements

The following table describes the elements returned by SearchBins.

SearchBins also returns the elements that all response groups return, as described in Elements Common to All Response Groups.

Parent Response Group

The following response groups are parent response groups of SearchBins.

  • None

Child Response Group

The following response groups are child response groups of SearchBins.

  • None

Sample REST Use Case

The following request uses the SearchBins response group.

Copy
http://webservices.amazon.com/onca/xml? Service=AWSECommerceService& AWSAccessKeyId=[AWS Access Key ID]& AssociateTag=[Associate ID]& Operation=ItemSearch& Condition=All& SearchIndex=SportingGoods& Keywords=Glove& ResponseGroup=SearchBins& Version=2013-08-01 &Timestamp=[YYYY-MM-DDThh:mm:ssZ] &Signature=[Request Signature]

Sample Response Snippet

The following response snippet shows the elements returned by SearchBins. Notice that the NarrowBy value is PriceRange.

Copy
<Item> <ASIN>B00005R2GR</ASIN> </Item> <Item> <ASIN>B00076ZDV8</ASIN> </Item> <Item> <ASIN>B00092FEEG</ASIN> </Item> <Item> <ASIN>B000ADTP1W</ASIN> </Item> <SearchBinSets> <SearchBinSet NarrowBy="PriceRange"> <Bin> <BinName>$25-$49</BinName> <BinItemCount>316</BinItemCount> <BinParameter> <Name>MinimumPrice</Name> <Value>2500</Value> </BinParameter> <BinParameter> <Name>MaximumPrice</Name> <Value>4999</Value> </BinParameter> </Bin> </SearchBinSet> <Bin> <BinName>$0-$24</BinName> <BinItemCount>280</BinItemCount> <BinParameter> <Name>MinimumPrice</Name> <Value>0</Value> </BinParameter> <BinParameter> <Name>MaximumPrice</Name> <Value>2499</Value> </BinParameter> </Bin> </SearchBinSet> <SearchBinSet NarrowBy="BrandName"> <Bin> <BinName>Rawlings</BinName> <BinItemCount>71</BinItemCount> <BinParameter> <Name>Brand</Name> <Value>Rawlings</Value> </BinParameter> </Bin> <Bin> <BinName>Body Glove</BinName> <BinItemCount>53</BinItemCount> <BinParameter> <Name>Brand</Name> <Value>Body Glove</Value> </BinParameter> </Bin> </SearchBinSet> <SearchBinSet NarrowBy="Subject"> <Bin> <BinName>Categories</BinName> <BinItemCount>860</BinItemCount> <BinParameter> <Name>BrowseNode</Name> <Value>3375301</Value> </BinParameter> </Bin> <Bin> <BinName>Baseball</BinName> <BinItemCount>311</BinItemCount> <BinParameter> <Name>BrowseNode</Name> <Value>3395731</Value> </BinParameter> </Bin> </SearchBinSet>