Categories for Buy APIs

Every item on eBay is assigned to a category but categories are not the same across all the eBay marketplaces. Several Buy API methods use the category ID to refine the results and some method require the category ID. The Commerce Taxonomy API, methods can help you discover categories that are appropriate to your area of focus, so you can present items to buyers in their areas of interest.

Categories are organized into a tree hierarchy. Approximately 20 eBay marketplaces each use a default category tree, which is typically structured differently for each marketplace. The category tree structure is also subject to change as categories are added, expanded, consolidated, or removed (users are notified of any changes).

Following is an example of using the Taxonomy API to discover the categories that apply to a buyers' areas of interest in a particular eBay marketplace. For more information about working with categories, see the Taxonomy API.

Identify the default category tree

Use the getDefaultCategoryTreeId method to identify the default category tree for your marketplace; for example:

GET https://api.ebay.com/commerce/taxonomy/v1/get_default_category_tree_id?marketplace_id=EBAY_US

The response payload contains the category tree ID and version:

{
  "categoryTreeId": "0",
  "categoryTreeVersion": "117"
}

You use the value of categoryTreeId to identify that tree in subsequent Taxonomy API methods.

Retrieve the complete category tree

You can maintain your own copy of the default category tree, and present the tree to buyers for browsing from the top down. Use the getCategoryTree method to retrieve the entire category tree:

GET https://api.ebay.com/commerce/taxonomy/v1/category_tree/0

This method can return a very large payload (tens of thousands of categories), so you are strongly advised to submit the request with the following HTTP header:

Accept-Encoding: gzip

With this header (in addition to the required headers described under HTTP Request Headers), the method returns the response with gzip compression.

The following severely trimmed example provides an idea of the category tree structure:

{
  "categoryTreeId": "0",
  "categoryTreeVersion": "117",
  "rootCategoryNode": {
    "category": {
      "categoryId": "0",
      "categoryName": "Root"
    },
    "childCategoryTreeNodes": [
      {
        "category": {
          "categoryId": "1",
          "categoryName": "Collectibles"
        },
        "parentCategoryTreeNodeHref": "https://api.ebay.com/commerce/taxonomy/v1/
			category_tree/0/get_category_subtree?category_id=1",
        "childCategoryTreeNodes": [
          {
            "category": {
              "categoryId": "34",
              "categoryName": "Advertising"
            },
            "parentCategoryTreeNodeHref": "https://api.ebay.com/commerce/taxonomy/v1/
			category_tree/0/get_category_subtree?category_id=34",
            "childCategoryTreeNodes": [
              {
                "category": {
                  "categoryId": "36",
                  "categoryName": "Soda"
                },
                "parentCategoryTreeNodeHref": "https://api.ebay.com/commerce/taxonomy/v1/
				category_tree/0/get_category_subtree?category_id=36",
                "childCategoryTreeNodes": [
                  {
                    "category": {
                      "categoryId": "13600",
                      "categoryName": "Coca-Cola"
                    },
                    "parentCategoryTreeNodeHref": "https://api.ebay.com/commerce/taxonomy/v1
					/category_tree/0/get_category_subtree?category_id=13600",
                    "childCategoryTreeNodes": [
                      {
                        "category": {
                          "categoryId": "38",
                          "categoryName": "Other Coca-Cola Ads"
                        },
                        "parentCategoryTreeNodeHref": "https://api.ebay.com/commerce/taxonomy/v1/
					category_tree/0/get_category_subtree?category_id=38",
                        "categoryTreeNodeLevel": 5,
                        "leafCategoryTreeNode": true
                      },
                         ...
                    ],
                    "categoryTreeNodeLevel": 4
                  },
                     ...
                ],
                "categoryTreeNodeLevel": 3
              },
                 ...
            ],
            "categoryTreeNodeLevel": 2
          },
             ...
        ],
        "categoryTreeNodeLevel": 1
      },
         ...
      {
        "category": {
          "categoryId": "172008",
          "categoryName": "Gift Cards & Coupons"
        },
        "parentCategoryTreeNodeHref": "https://api.ebay.com/commerce/taxonomy/v1/
			category_tree/0/get_category_subtree?category_id=172008",
        "childCategoryTreeNodes": [
           ...
        ],
        "categoryTreeNodeLevel": 1
      }
    ],
    "categoryTreeNodeLevel": 0
  },
  "applicableMarketplaceIds": []
}

With such a large set of categories, you will probably want to present a limited portion of the tree at a time to buyers, and reveal additional child categories when a buyer selects one at the current level. In addition to child categories, you can present the buyer with the items listed within the currently selected category. That set of items will become smaller and more focused as the buyer selects more restrictive categories.

You can enable buyers to search for items below the level of a selected category using the Browse API search method. When the buyer selects an item, you can retrieve the item details using the getItem method.

You will not need to retrieve this category tree again, unless eBay publishes a new version. You can determine this by using the getDefaultCategoryTreeId method to retrieve and compare the categoryTreeVersion field to the one you have cached.

For more information about working with categories, see the Taxonomy API.