Retrieving the Category Hierarchy for a Site  

To retrieve the data for the categories on a particular site, use GetCategories. Doing this involves three general steps: setting up the execution environment, specifying the data to return (category hierarchy version or the category hierarchy itself), and making the API call.

The ID for a category (one of the values returned by GetCategories) is one of the required inputs for listing a new item.

After retrieving the data for a site's category hierarchy, the application should store the information in some persistent form, such as in a database table. This data can then later be refreshed when a category hierarchy change is indicated (i.e., when the returned category hierarchy version is different than the last one the application retrieved).

Optionally, specify the eBay site for which to retrieve the category data. The category data varies for different sites. That is, the category hierarchy on the eBay US site is not the same as the category hierarchy on the eBay Germany site. If the category site ID is not specified, eBay will return category data for the site you specify in the request URL (see Routing the Request (Gateway URLs)).

Optionally specify the ID of a parent category to be returned as the top most category in the result set. If not specified, then the top most category returned is the root category for the target site. If a parent category is specified, then that is the top most category in the result set and only subcategories child to it (and their children) are returned. To determine the available category parent IDs, retrieve all category data the first time you execute GetCategories, and store the data. This may take several minutes. Subsequently, refer to your locally stored data for specific parent category IDs.

The depth of a category within the hierarchy is called a level. The top-most categories have a level of 1, their immediate children have a level of 2, and so on. Optionally, specify a limit on the number of levels of the category hierarchy to retrieve. If no level limit is specified, the result set will contain categories at all levels. If a level limit is specified, then only those categories having that depth level or less are returned. For example, if a value of 1 is specified, then only those categories child to the root category are returned. The categories that are grandchildren to the root category are not returned.

Optionally specify whether to retrieve all categories or only categories in which items can be listed (leaf categories). If you want to enable users to browse a hierarchical category structure to choose a category to list in, you should retrieve all categories. If you want to verify which leaf categories support a particular feature, you can retrieve only the leaf categories.

Table 3-1 GetCategories Data Specifiers 

Input Field	Required?	Type/Code List	Purpose
CategorySiteID	Y	string	Specifies the eBay site from which the call will retrieve the category data. Pass a string containing the numeric ID that identifies the site (e.g., "0" for US). See Site IDs.
CategoryParent	N	string	Specifies the category ID for the top most category to return (along with the subcategories under it, the value of the LevelLimit property determining how deep). May specify multiple top most categories and the hierarchies for each is returned.
LevelLimit	N	int	Specifies which category levels to return. Pass an int value as its input to retrieve all category nodes with a category level less than or equal to the LevelLimit value.
ViewAllNodes	N	boolean	If you specify a false value, only leaf categories are returned. If you specify a true value, all categories are returned.

The example below shows retrieving category data for the US eBay site. It requests categories up to three levels deep, returning both leaf and parent categories.

Example 3-1 Specifying the Category Data

<?xml version="1.0" encoding="utf-8"?> <GetCategoriesRequest xmlns="urn:ebay:apis:eBLBaseComponents"> <RequesterCredentials> <eBayAuthToken>ABC...123</eBayAuthToken> </RequesterCredentials> <CategorySiteID>0</CategorySiteID> <DetailLevel>ReturnAll</DetailLevel>   <LevelLimit>3</LevelLimit>   <ViewAllNodes>true</ViewAllNodes> </GetCategoriesRequest>

GetCategories returns in the response object a CategoryArray containing one or multiple (typically many) CategoryType elements, one for each of the categories on the specified eBay site.

Table 3-2 GetCategories Return Values 

Return Fields	Type/Code List	Purpose
CategoryArray	CategoryArrayType	List of the categories from the specified site (possibly limited to only those of a certain level, based on input). Contains one CategoryType object for each returned category, each of which contains the data for one category.
CategoryCount	int	Indicates the number of categories returned by the call.
UpdateTime	dateTime	Indicates the date and time the just-retrieved category hierarchy was last modified.
CategoryVersion	string	Indicates the update version for the just-retrieved category hierarchy.

An application needs to traverse the Category elements in the CategoryArray property of the response XML to visit each one and inspect its properties in order to store and work with the data in a useful way.

Each Category element returned has the properties for a category, such as the category ID, category name, its parent ID (if any), whether or not it is a leaf category in which items can be listed, and other information.

Category IDs are a required input for listing a new item (except Store Inventory items). The category names can be used by an application to populate a list in its user interface, from which the user can select the category in which to list a new item. The application should store the category data in some persistent manner (such as a database table) to have the data available whenever the application is run.

Different leaf categories can have the same names but different IDs. For example, under the general category of "Books", several leaf categories might exist called "Fantasy". In some cases, this is because the nature of the item is different (e.g., an audio book on CD vs. cassette). In other cases, it is because sellers may prefer to list items in particular parent categories in order to target buyers more carefully. Some examples of leaf categories with identical names might be:

Audio: Cassettes: Fiction: Fantasy
Audio: CDs: Fiction: Fantasy
Children: Fiction (Chapter Books): Early Readers: Fantasy
Children: Fiction (Chapter Books): Middle School: Fantasy
Fiction & Literature: Romance: Fantasy

All categories except those at the top level will have a parent category, and thus a non-zero value in CategoryParentID. Categories for which the LeafCategory value is true are at the bottom-most level of their branch in the hierarchy and have no child categories.

The combination of the CategoryID, CategoryParentID, and LeafCategory provide the information you need in order to represent the category hierarchy. With these values, you can traverse the hierarchy and enable users to drill down from higher-level categories to lower-level categories.

For example, an application might initially present a list of categories that are all at the same level. These are categories that all have the same CategoryLevel values. Of these categories, some will be container categories (i.e., the LeafCategory value is false). To drill down into the next level of one branch of the hierarchy, the application would use the CategoryID of one of those categories and then load all categories where the CategoryParentID is the same as that CategoryID (essentially loading all of that category's children). To drill down to the bottom of the category branch, this process can be repeated as many times as necessary until all the child categories are leaf categories (i.e., the LeafCategory value is true).

These fields can also be used to "walk" upwards in the hierarchy. To do that, find the category for which the CategoryID equals the CategoryParentID of the current category (i.e., find the current category's parent). To find sibling categories, find all of the parent category's child categories (those categories for which the CategoryParentID is the same as the CategoryID of the current category). You can use this information to design and present category-selection functionality in your application.

GetCategories also returns the date and time the category hierarchy was last updated and the version of the category hierarchy.

See Maintaining Category Data for information about how to refresh the locally stored category meta-data after it has been initially downloaded.

User-Contributed Notes