taxonomy APIv1.0.0

Taxonomy API Overview

Note: The General Availability (GA) version of the Taxonomy API has been released. With the exception of the URI change for all Taxonomy API endpoints ('v1' in the path instead of 'v1_beta'), no additional capabilities or schema elements have been added to this initial GA version of Taxonomy API. Developers currently using the Beta version should make plans to migrate to the new GA version, as the Beta version will be decommissioned on March 31, 2021. Until that date, the Beta version documentation set can be accessed through the All API Documentation page.

The Taxonomy API enables you to assist both sellers and buyers:

  • It helps sellers to determine the best eBay category under which to offer each inventory item for sale in a selected eBay marketplace. It helps sellers to select the categories of items to include in a campaign or promotion. It also provides information about the aspects to include when defining an inventory item in a given category. For more information, see the Selling Integration Guide.
  • It helps buyers to determine the appropriate categories in which to browse or search for the items they're looking to purchase in a particular eBay marketplace. For more information, see the Buying Integration Guide.

For more information about using RESTful APIs, see Using eBay Restful APIs.

Technical overview

During the process of offering a product for sale or finding a product to buy in a specific eBay marketplace, you use the Taxonomy API to discover which categories are available for that marketplace, then enable the seller or buyer to iterate through subsets of those categories, or to enter key words and phrases for category suggestions from eBay. The goal of this process is to help the seller or buyer select the most appropriate category or categories under which they can offer a product for sale or browse for a product to purchase, respectively.

Primary Taxonomy API objects

Objects are as follows:

  • Category The Category object defines a category in the eBay product catalog with a category ID and a name. An eBay category serves to identify:
    • a set of similar listings in an eBay marketplace, or
    • a set of more specific eBay categories

    Every eBay product category is located at a category tree node in an eBay category tree.

    Assigning a listing to an appropriate category helps to ensure that potential buyers can find that listing by browsing or searching within that category. Assigning a listing to the wrong category can severely damage the seller's ability to sell that listing.

  • Category Tree Node The CategoryTreeNode object identifies a location in an eBay category tree. It includes an associated Category object, and is designated as either:
    • a leaf node (its associated category identifies a set of similar listings), or
    • a parent node (its associated category identifies a set of more specific categories)

    A parent CategoryTreeNode object contains one or more nested category tree nodes.

  • Category Tree A category tree constitutes a complete hierarchical framework consisting of category tree nodes, each node with an associated eBay category. The CategoryTree object represents a category tree, which contains one root level parent category tree node, which in turn contains one or more nested category tree nodes.

    A given category tree can be the default tree used by one or more eBay marketplaces.

  • Category Subtree A category subtree constitutes a complete branch of a specified category tree. It consists of one or more category tree nodes, each node with an associated eBay category. The CategorySubtree object contains one non-root category tree node, which can be either a leaf node (which is thus the entire subtree) or a parent node (which in turn contains one or more nested category tree nodes).
  • Aspect An aspect is a predefined attribute associated with a leaf category, such as color or size. Each leaf category has its own set of aspects. The Aspect object contains the aspect name, its valid values, and constraints on the use of those values. Sellers must provide or select values for some aspects of a given category when using the Inventory API's createOrReplaceInventoryItem call to define inventory items in that category. Other aspects of the category may be available but not required.

The following diagram illustrates the relationships between the objects in an eBay category tree:

This category tree contains ten category tree nodes — five are leaf nodes, and all include a category. Each leaf node category identifies listings that belong to that category, and each non-leaf category identifies more specific categories.

Note: Although the root node's category identifies all of the categories in the tree, don't rely on its category name to be predictable or to provide meaningful information.

Business use cases

This section outlines the high-level use cases addressed by the Taxonomy API.

Discover a category to use for a listing or promotion

Before creating an eBay listing for an item, you can use the Taxonomy API to assist the seller to discover the category that's most appropriate. Assigning a listing to the wrong category can severely restrict the seller's ability to sell that item, so finding the best category match for an item is essential. You can also enable a seller to select categories to include in a promotion. When you publish an offer, include as item specifics the category aspects that are required.

Discover categories for buyers to browse or search for items

Before buyers search for eBay items in your buying application, you can use the Taxonomy API to present them with the full category tree for the eBay marketplace, so they can browse the tree hierarchy to narrow their search focus to categories in their areas of interest. This way you can identify the categories that cover the items your buyers might want to purchase, while minimizing the number of unwanted items that might clutter up the search results.

API restrictions

Supported marketplaces

Currently the Taxonomy API is supported in at least 20 marketplaces. For a list, see Marketplaces with Default Category Trees.

Rate limits

The number of calls you can make per day using the Taxonomy API depends on your application's eBay compatibility level:

  • Tier 1 applications: 5,000 calls/day
  • eBay compatible applications: 1 million calls/day