Refining a Search with Aspect Filters

The search calls, such as findItemsByKeywords and findItemsAdvanced can return aspect metadata that can be used to refine searches. The metadata is returned in the form of a histogram, which contains the name of the category that is most pertinent to your search, and information for all of the aspects (e.g., Brand) used in the category.

To refine a search by category, use findItemsAdvanced and the categoryID field.

Aspects are item characteristics, such as brand, product type, size, which are shared by certain types of items. For example, for Shoes, aspects include Style, Color, and Shoe Size. For Digital Cameras, aspects include Product Type, Brand, Megapixels, and Optical Zoom. These aspect values come from listing properties, such as item specifics, titles, and subtitles. This aspect information can be used to create filters to refine your search results.

Retrieving Aspect Histograms with Search Results

When you search for items with one of the finding calls in the Finding API, you can optionally request an aspect histogram (e.g., outputSelector=AspectHistogram). The histogram provides information you can use to refine your search. The histogram lists all the aspects (e.g., Brand or Size) used in the category. For each aspect, all aspect values (e.g., brand names) are listed with the number of active listings that match a given aspect value. Aspect filters consist of an aspect name, and one or more aspect value names. An aspect value is returned only if there are active listings associated with the value.

Not all searches will return an aspect histogram. Searching for items in categories that do not support aspects will not return an aspect histogram. Also, if your search is too broad, it may not return an aspect histogram. For example, searching with just "ipod" in your keywords may not return a histogram, but "ipod nano" will.

Aspect data varies by category. For example, although the category for women's dresses and the category for wedding dresses may have some similar aspects, such as size, many aspects differ between the two categories. When the response does contain an aspect histogram, it is returned for the category that is most pertinent to your search. Note that aspect data is based on information from currently active items only. You should not store and reuse the aspect data.

If you search the eBay site for digital cameras, you may get an aspect histogram that looks like the following sample:

...
  <aspectHistogramContainer>
    <domainName>Digital_Cameras</domainName>
    <domainDisplayName>Digital Cameras</domainDisplayName>
    <aspect name="Brand">
      <valueHistogram valueName="Canon">
        <count>198</count>
      </valueHistogram>
      <valueHistogram valueName="Casio">
        <count>2</count>
      </valueHistogram>
      <valueHistogram valueName="Kodak">
        <count>12</count>
      </valueHistogram>
      <valueHistogram valueName="Konica">
        <count>14</count>
      </valueHistogram>
      <valueHistogram valueName="Konica Minolta">
        <count>12</count>
      </valueHistogram>
      <valueHistogram valueName="Minolta">
        <count>2</count> 
      </valueHistogram>
      <valueHistogram valueName="Mustek">
        <count>1</count>
      </valueHistogram>
      <valueHistogram valueName="Nikon">
        <count>26</count>
      </valueHistogram>
      <valueHistogram valueName="Olympus">
        <count>15</count>
      </valueHistogram>
      <valueHistogram valueName="Panasonic">
        <count>579</count>
      </valueHistogram>
      <valueHistogram valueName="Sony">
        <count>105</count>
      </valueHistogram>
      <valueHistogram valueName="Not Specified">
         <count>66</count>
      </valueHistogram>
    </aspect>
    <aspect name="Type">
      <valueHistogram valueName="Point & Shoot">
        <count>710</count>
      </valueHistogram>
      <valueHistogram valueName="SLR, Professional">
        <count>17</count>
      </valueHistogram>
      <valueHistogram valueName="Spy & Miniature">
        <count>2</count>
      </valueHistogram>
      <valueHistogram valueName="Underwater">
        <count>22</count>
      </valueHistogram>
      <valueHistogram valueName="Not Specified">
        <count>282</count>
      </valueHistogram>
    </aspect>
    ...
  </aspectHistogramContainer>
...

Constructing Filters

Aspect filters are constructed from data in the aspect histogram. For example, highlighted data in the following histogram can be used to create an aspect filter to refine your digital camera search to return only underwater cameras (of which there are 22):

...
  <aspectHistogramContainer>
    <domainName>Digital_Cameras</domainName>
    <domainDisplayName>Digital Cameras</domainDisplayName>
          ...
    <aspect name="Type">
      <valueHistogram valueName="Point & Shoot">
        <count>710</count>
      </valueHistogram>
          ...
     <valueHistogram valueName="Underwater">
        <count>22</count>
      </valueHistogram>
          ...
    </aspect>
    ...
  </aspectHistogramContainer>
...	

Here's a corresponding aspect filter, which limits your search to underwater cameras only:

<aspectFilter>
  <aspectName>Type</aspectName>
  <aspectValueName>Underwater</aspectValueName>
</aspectFilter>

In a URL request, the same filter will look like this:

...&aspectFilter.aspectName=Type&aspectFilter.aspectValueName=Underwater...