Use Search Bins to Find Items
Up to this point, you have seen how you can use operation input parameters and response groups to filter out unwanted responses. The SearchBins response group provides a different means of refining results. It enables you to filter results based on values returned in a response.
The SearchBins response group categorizes the items returned by
ItemSearch into groups, called bins. The grouping is based on some
criteria, depending on the search index. For example, a set of bins can be based on a
set of price ranges for an item. In the case of women’s shoes, for example, SearchBins
might return a bin that contains 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 advantage of using search bins is that the response group divides the items into
bins without you having to return or parse item attributes. You can then submit a second
ItemSearch request and return only the items in one bin.
You cannot create bins nor can you specify the criteria used to divide the items into groups. The SearchBins response group does that automatically.
Some search indices support more than one kind of bin. For example, apparel items can be divided in to bins according to price range and brand. In this case, the response would return multiple sets of bins, called SearchBinSets, in which the items would be divided according to different criteria.
The criteria used to divide the returned items into bins is called the NarrowBy value.
Search bins are only available in the US locale.
Search Bin Example
The following request uses the SearchBins response group to return search bins.
[Access Key ID]& AssociateTag=
[Associate Tag]& Operation=
ItemSearch& SearchIndex=Baby& Keywords=pants& Availability=Available& Condition=All& ResponseGroup=SearchBins &Timestamp=[YYYY-MM-DDThh:mm:ssZ] &Signature=[Request Signature]
The following XML is a snippet from the response.
<SearchBinSets> <SearchBinSet NarrowBy="PriceRange"> <Bin> <BinName>$0$24</BinName> <BinItemCount>1645</BinItemCount> <BinParameter> <Name>MinimumPrice</Name> <Value>0</Value> </BinParameter> <BinParameter> <Name>MaximumPrice</Name> <Value>2499</Value> </BinParameter> </Bin> <Bin> <BinName>$25$49</BinName> <BinItemCount>647</BinItemCount> <BinParameter> <Name>MinimumPrice</Name> <Value>2500</Value> </BinParameter> <BinParameter> <Name>MaximumPrice</Name> <Value>4999</Value> </BinParameter> </Bin> <Bin> <BinName>$50$99</BinName> <BinItemCount>173</BinItemCount> <BinParameter> <Name>MinimumPrice</Name> <Value>5000</Value> </BinParameter> <BinParameter> <Name>MaximumPrice</Name> <Value>9999</Value> </BinParameter> </Bin>
This response snippet shows the first three bins in the response. The NarrowBy value shows that the items were divided up based on price range. The BinName element names the bin. The names are descriptive of the price ranges that each bin represents. For example, the BinName, $50$99, contains items that cost between $50 and $99.99, which you can see by the values returned for MinimumPrice and MaximumPrice in that bin. The BinItemCount element shows how many items are in each bin, for example, there are 173 items in the last bin.
The BinParameter/Value elements show the values used to create the bins. In this example, the parameters are the minimum and maximum prices of the items in that bin. For example, in the last bin, the minimum price of an item in that bin is $50.00 and the maximum value is $99.99.
The BinParameter/Name value, such as MaximumPrice, is an
ItemSearch parameter name. This means that you can use the
<Value> as the value for the parameter named by <Name> in a subsequent
ItemSearch request. In this example,
MinimumPrice is the
parameter and, in the last bin, the value is 5000. By submitting a second request
MaximumPrice , you could
return the item attributes for only the items in that bin.
As you can see from this example, the SearchBins response group enables you to narrow your search without you having to parse through item attributes.
Results Refined by Repeating ItemSearch Requests
One value of using search bins is that you can divide items into groups according
to criteria without having to parse item attributes. Based on the search bins
returned, you can then submit a second request using the
ItemSearch parameter value that helps target your results, but
The names of bins and the parameters that describe the bins vary according to the bin. The following sample shows a bin based on price.
<SearchBinSetNarrowBy="PriceRange"> <Bin> <BinName>$0$24</BinName> <BinItemCount>1645</BinItemCount> <BinParameter> <Name>MinimumPrice</Name> <Value>9</Value> </BinParameter> <BinParameter> <Name>MaximumPrice</Name> <Value>2499</Value> </BinParameter> </Bin>
The response shows the minimum and maximum price for items in the bin, $0$24, and the number of items in it, 1645.
Other NarrowBy values name bins differently.
As you can see from these examples, BinParameter names are the same as
ItemSearch input parameter names. This correspondence means that you
can create a second
ItemSearch request using the search bin
results as values for
ItemSearch parameter values. For example,
returned in search bins based on
PriceRange. You could take
the values of the search bin and put them directly into
ItemSearch parameters. Using the preceding PriceRange example, you
could write the following
ItemSearch request to retrieve items
only in the first search bin.
http://webservices.amazon.com/onca/xml? Service=AWSECommerceService& AWSAccessKeyId=
[AWS Access Key ID]& AssociateTag=
[Associate Tag]& Operation=
ItemSearch& SearchIndex=Baby& Keywords=pants& Availability=Available& Condition=All& MinimumPrice=0& MaximumPrice=2499& ResponseGroup=SearchBins &Timestamp=[YYYY-MM-DDThh:mm:ssZ] &Signature=[Request Signature]
ItemSearch divides the results of this request into another set
of search bins because the SearchBins response group was used again. This means that
the price range of the first search bin in the first response is split into multiple
search bins in the response to the second request. The second response enables you
to present more granularity in price ranges. For example, from the first response,
you could return all items that cost between $0 and $24.99. In the second response,
you are able to provide a much smaller price interval, for example, $10 to
To refine search results using SearchBin
Include the SearchBins response group in an ItemSearch request.
The response includes the narrowby value and results grouped by bins.
Use related ItemSearch parameters to send a second request to return results related to only those items within the specified bin.
For example, if the
PriceRange, the related
If you want to refine the results further, use the SearchBins response group in a second request and repeat the procedure.
The process of using search bin results for
parameter values can be iterative. You can, for example, submit a third request
using the SearchBins response group to divide one search bin into more search bins.
This process can be repeated until the level of granularity you desire is reached.
At that point, you can send a last request using other response groups of your
Alternatively, you could refine the search results in a different way. Some search
indices return more than one set of search bins. In those cases, you can use the
values from more than one set of search bins in an
request. Using the preceding example, if the response also included a search bin
based on BrandName, which is the NarrowBy value, you could use brand and price range
values in an
Brand=Levi’s& MinimumPrice=0& MaximumPrice=2499&
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.
ItemSearch Request Tips
Here are some tips to help you create accurate ItemSearch requests.
If you want to find only items sold by Amazon, set the MerchantId parameter to "Amazon". (Note: Amazon sells only new items).
Keywordsparameter searches for word matches in an item's title and description. If you know a word is part of the title of an item, use the Title parameter because, in this case, it often returns fewer but more accurate results than the Keywords parameter.
To use Boolean values, such as AND, NOT, or OR, in an
ItemSearchrequest, use the Power parameter. You can create relatively sophisticated search criteria using this parameter. For more information, see ItemSearch.