taxonomy beta APIv1_beta.7.0

Taxonomy API (Beta version)

Note: The Beta version of the Taxonomy API has been deprecated, and will be decommissioned on March 31, 2021. Developers currently using the Beta version should make plans to migrate to the newly-released General Availability (GA) version of the Taxonomy API. The new GA 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.
  • Contains two operations to retrieve metadata on compatible vehicle aspect names and values, and this metadata is used to specify which vehicles are compatible with parts and accessories listings.
  • 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.

This section outlines the primary objects used by the Taxonomy API.

Note: In addition to the API, there is an open source Taxonomy SDK. This SDK is used to compare the aspect metadata that is retrieved using the fetchItemAspects resource method. We trust the release of Taxonomy API bulk download capability for aspects metadata combined with this SDK brings transparency to the evolution of our metadata for our partners.

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.
  • Compatibility Properties – A compatibility property is a predefined motor vehicle aspect that is associated with a specific leaf category within an eBay marketplace that supports parts and compatibility. Examples for a US or US Motors category may include 'Year', 'Make', 'Model', 'Trim', and 'Engine'. Compatibility properties can vary by eBay marketplace and category.
  • Compatibility Property Values – Compatibility property values are returned with the getCompatibilityPropertyValues method, and the values that are returned is determined by the specified compatibility property and the filters that are used in URI.

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.

Retrieve metadata on compatible vehicle aspect names and values

Compatible vehicle aspect names and values are used to specify which vehicles are compatible with parts and accessories listings. The seller can use this metadata with the createOrReplaceProductCompatibility method of the Inventory API to create a list of motor vehicles that are compatible with a motor vehicle part or accessory product.

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

The Taxonomy API is supported in all eBay marketplaces. For a list, see Marketplaces with Default Category Trees.

However, the getCompatibilityProperties and getCompatibilityPropertyValues are only applicable to the following eBay marketplaces that support Parts Compatibility: eBay Motors US, eBay Canada, eBay UK, eBay Germany, eBay Australia, eBay France, eBay Italy, and eBay Spain.

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