This doc page has moved! You should be automatically redirected to the new location. If you are not redirected automatically, follow this link to the new page.

You are here: Sell APIs > Selling Integration Guide > Finding a Category

Finding Categories for a Listing or Promotion

Every item that a seller wants to sell on eBay must be assigned to a category under which the item will be listed or promoted. 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 restrict the seller's ability to sell that item. Before creating a listing or a promotion for an item, you can use the Taxonomy API to assist the seller to discover the category that's appropriate for the item.

Topics:

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).

Note: Currently, for each eBay marketplace the default category tree is the only category tree available. This will change in the future as new category trees are developed for more specialized uses.

Following is an example of the Taxonomy API workflow for discovering the category that best applies to a particular item in a particular eBay marketplace. If a seller wants to sell an item related to the iPhone, you can discover the most appropriate leaf categories that apply to the iPhone. Use the Taxonomy API to accomplish this.

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

Identify the default category tree for a marketplace

Use the Get a Default Category Tree ID call to identify the default category tree for your marketplace; for example:

GET https://api.ebay.com/commerce/taxonomy/v1_beta/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 calls.

Retrieve suggested categories

You can apply eBay's functionality to recommend categories for your sellers to use to list their items. Use the Get Suggested Categories call to retrieve an array of category tree leaf nodes in the specified category tree that are considered by eBay to most closely correspond to the query string provided:

GET https://api.ebay.com/commerce/taxonomy/v1_beta/category_tree/0/get_category_suggestions?q=iphone

The response payload contains several leaf category nodes (shown in bold), along with their ancestor nodes extending up to the tree's root. Note that more categories were returned, but some have been removed for readability:

{
  "categorySuggestions": [
    {
      "category": {
        "categoryId": "9355",
        "categoryName": "Cell Phones & Smartphones"
      },
      "categoryTreeNodeLevel": 2,
      "categoryTreeNodeAncestors": [
        {
          "categoryId": "15032",
          "categoryName": "Cell Phones & Accessories",
          "categoryTreeNodeLevel": 1,
          "categorySubtreeNodeHref": "https://api.ebay.com/commerce/taxonomy/v1_beta/
			category_tree/0/get_category_subtree?category_id=15032"
        }
      ]
    },
    
      ...
    
    {
      "category": {
        "categoryId": "20349",
        "categoryName": "Cases, Covers & Skins"
      },
      "categoryTreeNodeLevel": 3,
      "categoryTreeNodeAncestors": [
        {
          "categoryId": "9394",
          "categoryName": "Cell Phone Accessories",
          "categoryTreeNodeLevel": 2,
          "categorySubtreeNodeHref": "https://api.ebay.com/commerce/taxonomy/v1_beta/
			category_tree/0/get_category_subtree?category_id=9394"
        },
        {
          "categoryId": "15032",
          "categoryName": "Cell Phones & Accessories",
          "categoryTreeNodeLevel": 1,
          "categorySubtreeNodeHref": "https://api.ebay.com/commerce/taxonomy/v1_beta
			/category_tree/0/get_category_subtree?category_id=15032"
        }
      ]
    },
    
      ...
    
    {
      "category": {
        "categoryId": "58543",
        "categoryName": "Accessory Bundles"
      },
      "categoryTreeNodeLevel": 3,
      "categoryTreeNodeAncestors": [
        {
          "categoryId": "9394",
          "categoryName": "Cell Phone Accessories",
          "categoryTreeNodeLevel": 2,
          "categorySubtreeNodeHref": "https://api.ebay.com/commerce/taxonomy/v1_beta/
			category_tree/0/get_category_subtree?category_id=9394"
        },
        {
          "categoryId": "15032",
          "categoryName": "Cell Phones & Accessories",
          "categoryTreeNodeLevel": 1,
          "categorySubtreeNodeHref": "https://api.ebay.com/commerce/taxonomy/v1_beta/
			category_tree/0/get_category_subtree?category_id=15032"
        }
      ]
    },
    {
      "category": {
        "categoryId": "45071",
        "categoryName": "Cell Phones"
      },
      "categoryTreeNodeLevel": 3,
      "categoryTreeNodeAncestors": [
        {
          "categoryId": "45065",
          "categoryName": "Wholesale Lots",
          "categoryTreeNodeLevel": 2,
          "categorySubtreeNodeHref": "https://api.ebay.com/commerce/taxonomy/v1_beta/
			category_tree/0/get_category_subtree?category_id=45065"
        },
        {
          "categoryId": "15032",
          "categoryName": "Cell Phones & Accessories",
          "categoryTreeNodeLevel": 1,
          "categorySubtreeNodeHref": "https://api.ebay.com/commerce/taxonomy/v1_beta/
			category_tree/0/get_category_subtree?category_id=15032"
        }
      ]
    }
  ],
  "categoryTreeId": "0",
  "categoryTreeVersion": "117"
}

You can present these categories to your seller, so the seller can select a leaf category for the listing or promotion. For more information about working with categories, see the Taxonomy API.

Retrieve the complete category tree

You can maintain your own copy of the default category tree, and enable sellers to browse or search the tree hierarchy and select the category for an item promotion. Use the Get a Category Tree call to retrieve the entire category tree:

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

This call 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: application/gzip

With this header (in addition to the required headers described under HTTP Request Headers), the call 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_beta/
			category_tree/0/get_category_subtree?category_id=1",
        "childCategoryTreeNodes": [
          {
            "category": {
              "categoryId": "34",
              "categoryName": "Advertising"
            },
            "parentCategoryTreeNodeHref": "https://api.ebay.com/commerce/taxonomy/v1_beta/
			category_tree/0/get_category_subtree?category_id=34",
            "childCategoryTreeNodes": [
              {
                "category": {
                  "categoryId": "36",
                  "categoryName": "Soda"
                },
                "parentCategoryTreeNodeHref": "https://api.ebay.com/commerce/taxonomy/v1_beta/
				category_tree/0/get_category_subtree?category_id=36",
                "childCategoryTreeNodes": [
                  {
                    "category": {
                      "categoryId": "13600",
                      "categoryName": "Coca-Cola"
                    },
                    "parentCategoryTreeNodeHref": "https://api.ebay.com/commerce/taxonomy/v1_beta
					/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_beta/
					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_beta/
			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 sellers, and reveal additional child categories when a seller selects one at the current level.

You will not need to retrieve this category tree again, unless eBay publishes a new version. You can determine this by using the Get a Default Category Tree ID call to retrieve and compare the categoryTreeVersion field to the one you have cached.