Using Search Bins to Find Items

From Product Advertising API: 2009-11-01

previous page next page

Using Search Bins to Find Items

Topics

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.

	Note
	Search bins are only available in the US locale.

Related Topics

SearchBins Response Group

Search Bin Example

The following request uses the SearchBins response group to return search bins.

Service=AWSECommerceService&
AWSAccessKeyId=[Access Key ID]&
Operation=ItemSearch&
SearchIndex=Baby&
Keywords=pants&
Availability=Available&
MerchantId=All&
Condition=All&
ResponseGroup=SearchBins

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 ItemSearch parameter and, in the last bin, the value is 5000. By submitting a second request using ItemSearch's parameters, MinimumPrice and 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 how?

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. The following example shows a response snippet when NarrowBy is “Merchant.” In this case, the BinParameter name is merchant ID.

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

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, MinimumPrice and MaximumPrice are 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://ecs.amazonaws.com/onca/xml?
Service=AWSECommerceService&
AWSAccessKeyId=[AWS Access Key ID]&
Operation=ItemSearch&
SearchIndex=Baby&
Keywords=pants&
Availability=Available&
Condition=All&
MinimumPrice=0& MaximumPrice=2499&
ResponseGroup=SearchBins

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

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 NarrowBy value is PriceRange, the related ItemSearch parameters are MinimumPrice and MaximumPrice.
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 ItemSearch 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 choosing.

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

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.

The default value of the Condition parameter is "New."

If you do not get satisfactory results and you have not specified a Condition, set the parameter to "All." This value returns all Conditions. If you change the value to something besides the default, New, you must also set the MerchantId parameter to "All." If you do not, you will get the same results. The reason is that the default value of MerchantId is Amazon. Because Amazon only sells new items, the response can only contain new items, which was the case when Condition was New, the default value. Setting MerchantId to "All" enables the response to contain merchants that sell items in all conditions.

The default value of the MerchantId parameter is "Amazon."

If you want to find items sold by other merchants or items that are not in "New" condition (Amazon only sells new items), either specify the merchant using MerchantId, or, to search all merchants, set the parameter to "All."

The Keywords parameter 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.

Use the TextStream parameter to search using a block of text.

For more information, see ItemSearch.

To use boolean values, such as AND, NOT, or OR, in an ItemSearch request, use the Power parameter.

You can create relatively sophisticated search criteria using this parameter. For more information, see ItemSearch.

previous page start next page