Retrieving Histogram Metadata

The histogram data returned by the Finding API provides statistics about the distribution of active items across categories and/or the distribution of active items associated with specific aspect values or item conditions.

Histogram data can help you refine search results to better locate relevant items.

Category Histograms

Category histograms return statistics for categories that match your search query or for a specified eBay category. You can retrieve a category histogram with the getHistograms call, or you can retrieve it with any of the search calls (e.g., findItemsByKeywords) by setting the outputSelector to CategoryHistogram. The histogram information consists of the following data for the specified category or category that best matches your search query, as well as for the immediate children categories:

• Category ID

• Category Name

• Item count

For getHistograms and finding calls that take categoryId as input (i.e., findItemsByCategory, findItemsAdvanced, and findItemsIneBayStore), category histograms are typically returned for non-leaf categories only. For example, the category IDs returned for items in search results are for the leaf categories in which the items are listed. If you use these category IDs as input for finding calls or getHistograms, the response will not return a category histogram.

Aspect Histograms

Aspect histograms return statistics about aspects that match your search query or for a specified eBay category. Aspects are well-known, standardized characteristics of an item. For example, "Screen Size," "Processor Type," and "Processor Speed" could be aspects of Laptop PCs. Aspects can vary for different kinds of items. For example, the aspects of Laptop PCs are different from those of Women's Dresses (aspects for Women's Dresses might include "Sleeve Style," "Dress Length," and "Size"). Aspect histograms are returned for the category that is most pertinent to your search.

Along with the category name, the aspect histogram information consists of the following data for each aspect in the category:

• Aspect name (e.g., Brand)

• Aspect value name (e.g., Canon)

• Item count associated with a given aspect value

Aspect histogram information, such as the aspectHistogramContainer.domainName value, the value of the name attribute of aspectHistogramContainer.aspect, the value of the valueName attribute of aspectHistogramContainer.aspect.valueHistogram, and associated counts can be used in the user interface, just as eBay does in the left panel of search pages:

For getHistograms and finding calls that take categoryId as input (i.e., findItemsByCategory, findItemsAdvanced, and findItemsIneBayStore), aspect histograms are returned for those categories only.

The aspect and category metadata can also be used to create aspect and category filters to further refine your search results. See Refining a Search with Aspect Filters for details.

Condition Histograms

Condition histograms return statistics about the condition of the items that match your search query. That is, they indicate how many items are new, used, refurbished, or in some other condition.

For users who are only interested in new items, condition histograms can provide a useful view of the number of brand new, "new other (see details)", and "like new" items available. For users who are curious about used items, condition histograms can provide a quick view of the range of used items available.

You retrieve a condition histogram with any of the search calls (e.g., findItemsByKeywords) by setting the outputSelector to ConditionHistogram, or by using the getHistograms call. The histogram information consists of the following data for each condition:

• Condition ID (e.g., 1000)

• Condition display name (e.g., "Brand new")

• Item count

Condition histograms only count items that have condition IDs.

Condition histograms are not returned in search calls when you use Condition as an item filter to narrow your search based on specific conditions. That is, they are only available before you have chosen to filter items based on condition.