The SearchBins Response Group categorizes the items returned by ItemSearch into bins. A set of bins, for example, can be a set of price ranges for a product. In the case of women’s shoes, for example, 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 information returned in the bins is the raw XML data that Amazon uses to create its retail Web site. You can use the raw XML data to create your own Web site.
US only
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:
<SearchBinSet NarrowBy="PriceRange">
For another product category, the NarrowBy attribute might be different, for example:
<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 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.
SpecialSize—Uncommon sizes an item comes in. Examples are "Plus Size & Tall," "Misses," "Maternity," "Husky," "Petites," and "Big & Tall."
Merchant—All merchants selling an item. This bin returns all merchants even if MerchantId is set to a single merchant in the ItemSearch request. In the response, the ASINs returned will be specific to the MerchantId specified in the request. The merchants listed in the Merchant bin can be used to list other merchants that sell the same ASIN. There are some items sold by only one merchant. In that case, the Merchant bin returns with only that merchant.
All Search Indices return the Subject bin. Most return all of the bins.
The following list shows which NarrowBy values are returned by each Search Index:
Apparel—Subject, BrandName, PriceRange, SpecialSize, Merchant
Baby—Subject, BrandName, PriceRange, SpecialSize, Merchant
Beauty—Subject, BrandName, PriceRange, SpecialSize, Merchant
Blended—Not supported
Books—Subject
Classical—Subject
DVD—Subject
Electronics—Subject, BrandName, PriceRange, SpecialSize, Merchant
Garden—Subject, BrandName, PriceRange, SpecialSize, Merchant
GourmetFood—Subject, BrandName, PriceRange, SpecialSize, Merchant
HealthPersonalCare—Subject, BrandName, PriceRange, SpecialSize, Merchant
Jewelry—Subject, BrandName, PriceRange, SpecialSize, Merchant
Kitchen—Subject, BrandName, PriceRange, SpecialSize, Merchant
Magazines—Subject
Merchants—Subject, BrandName, PriceRange, SpecialSize, Merchant
MusicalInstruments—Subject, BrandName, PriceRange, SpecialSize, Merchant
Miscellaneous—Subject, BrandName, PriceRange, SpecialSize, Merchant
Music—Subject
OfficeProducts—Subject, BrandName, PriceRange, SpecialSize, Merchant
PCHardware—Subject, BrandName, PriceRange, SpecialSize, Merchant
Photo—Subject, BrandName, PriceRange, SpecialSize, Merchant
Restaurants—Not supported
Showtimes—Theater
Software—Subject, BrandName, PriceRange, SpecialSize, Merchant
SportingGoods—Subject, BrandName, PriceRange, SpecialSize, Merchant
Theatrical—Subject
Tools—Subject, BrandName, PriceRange, SpecialSize, Merchant
Toys—Subject, BrandName, PriceRange, SpecialSize, Merchant
Travel—Subject
VHS—Subject
Video—Subject
VideoGames—Subject, BrandName, PriceRange, SpecialSize, Merchant
Wireless—Subject
WirelessAccessories—Subject
The element tags in a bin vary according to the bin. For example, in bins based on price, the elements and Name values are:
<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:
<Bin> <BinName> <BinItemCount> <BinParameter> <Name>Brand</Name> <Value>
You cannot specify the element tags returned in a bin.
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:
&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
&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.
The following request asks for shirts:
http://webservices.amazon.com/onca/xml? Service=AWSECommerceService& AWSAccessKeyId=[Your Access Key ID Here]& Operation=ItemSearch& MerchantId=A363XKZVKSMVXW& Condition=All& SearchIndex=SportingGoods& Keywords=Glove& ResponseGroup=SearchBins
The following response snippet shows the first ASINS and the first two bins for each NarrowBy value returned in the response:
<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="Merchant"> <Bin> <BinName>Sports"R"Us</BinName> <BinItemCount>860</BinItemCount> <BinParameter> <Name>MerchantId</Name> <Value>A363XKZVKSMVXW</Value> </BinParameter> </Bin> <Bin> <BinName>Target</BinName> <BinItemCount>8</BinItemCount> <BinParameter> <Name>MerchantId</Name> <Value>A1VC38T7YXB528</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>
The response has two large parts. The first part is the list of ASINs that satisfy the request. The remainder of the response shows the first two bins in each NarrowBy value. There are several things to notice:
Even though the ASINS returned are sold only by the merchant whose ID was included in the request, the Merchant bin shows other merchants that also sell the same ASIN. Typically, the merchant whose ID was included in the request, is listed first in the Merchant bin. Use the additional merchants in the Merchant bin to offer additional sales opportunities to customers.
Although the SportingGoods Search Index can potentially return five NarrowBy values, only four are returned in this example because the number of items in the NarrowBy value, SpecialSize, was zero.
BrowseNodes are related in a hierarchy where one BrowseNode can have zero or more ancestor and child BrowseNodes, as shown in the following figure.
This diagram shows five BrowseNodes and their hierarchy. Node A might be, for example, Shoes. Node B might be Women. Node C, a child of BrowseNodes A and B, might be Women’s Shoes.
The number inside each node represents the number of items in the BrowseNode when ItemSearch is called on Node A. BrowseNode C is a subset of BrowseNode A and a subset of BrowseNode B. Perhaps fifty of the items in BrowseNode C are also in BrowseNode A. When ItemSearch was run on BrowseNode A, the operation returned that BrowseNode A has 200 items. When ItemSearch is repeated using a BinParameter Name value that was returned in the first ItemSearch request, it is the same as running ItemSearch on a child of BrowseNode A, which, in this case, is BrowseNode C. By narrowing the search to only those values found in BrowseNode C, ItemSearch returns only those items in BrowseNode A that are also in BrowseNode C. As shown in the following figure, the number of common items is 35.
As a result, ItemSearch returns that BrowseNode A now only contains 35 items. While the change in the item count in BrowseNode A might, at first, be confusing, understanding that ItemSearch is returning only the intersection of BrowseNodes A and C explains why the number of items in BrowseNode A changes. Notice that the item counts in other BrowseNodes can also change.
Because the number of items in surrounding BrowseNodes can change with each new drilldown using ItemSearch, the BrowseNodes that contain the greatest number of items can change dramatically. In the previous discussion, for example, the number of items in BrowseNode A changed from 200 to 35 on successive ItemSearch requests. Because ItemSearch returns only the top ten BrowseNodes that contain the most items, the identity of the top ten BrowseNodes can change with each ItemSearch.