Related Topics

• SearchBins Response Group

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.

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.

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.

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.