Retrieving the Category Hierarchy for a Site

To retrieve the data for the categories on a particular eBay 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.

An application can retrieve the entire eBay category hierarchy or one or more parent (non-leaf) categories and all or some of those categories' child categories. All GetCategories responses include the version number of the eBay category hierarchy, as well as an UpdateTime timestamp to indicate when the last update to the hierarchy occurred. Generally, eBay updates the category hierarchy no more than once every few months. An application should be set up to check the category version occasionally, and only retrieve the category hierarchy when it has changed, saving unnecessary download time, activity, and bandwidth.

Every category that satisfies the search filters is returned under the CategoryArray object. Each category is represented by a separate Category object. 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.

Optionally, specify the ID of one or more parent (non-leaf) categories and all or some of those categories' child categories. To determine the available category parent IDs, retrieve all category data the first time you execute GetCategories, and store the data. The parent category of each returned category is returned in the CategoryParentID field. Note that top-level eBay categories, or L1 categories, do not have parent categories. The CategoryParentID field is still returned for L1 categories but this ID is the actual ID of the L1 category, and the same value that will be in the CategoryID field for that category.

As mentioned earlier, the top-most categories in the eBay hierarchy have a level of 1, their immediate children have a level of 2, and so on. If a user only wanted to retrieve all L1 categories (and none of the children), the LevelLimit field would be included and set to 1. If the user wanted to retrieve all L1 categories and their direct children (all L2 categories), the LevelLimit field would be included and set to 2. If the LevelLimit field is not used (or used, but set to a value higher than the 'deepest' L1 category), all child categories down to the leaf categories are returned in the response. The CategoryLevel value is returned for every category in the response, and a LeafCategory boolean field (returned as true) will be returned for all leaf categories. eBay items may only be listed in leaf categories..

After retrieving the data for a site's category hierarchy, the application should store the information for later use 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). While an application may use a transient storage method where the data exists only for the duration of the application's session, a persistent method of storing category data is preferred. If transient storage is used, the application must retrieve the category data from eBay each time the application is run. This is very inefficient and can be very time-consuming.

An application needs to traverse all Category objects in the CategoryArray container of the response to inspect each category's ID and properties in order to store and work with the data in a useful way.

For details about how to invoke the various options and work with the response data, see the GetCategories call reference.

Your application can use the returned category names to populate a browser 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.

Category IDs are unique, but category names are not. For example, several categories currently exist called "Fantasy." Each of these categories is located in a different part of the category hierarchy, and each is assigned a different category ID, as shown in the following example.

Category Hierarchies for Different 'Fantasy' Categories

Dolls & Bears (237)
    Dolls (238)
        Art Dolls-OOAK (2404)
            Fantasy (84626)
        By Material (15999)
            Porcelain (45444)
                Contemporary (1980-Now) (48958)
                    Fantasy (48961)
Toys & Hobbies (220)
    Action Figures (246)
        Fantasy (175693)
    Games (233)
        Miniatures, War Games (16486)
            Warhammer (31398)
                Fantasy (44409)
        Role Playing Games (2543)
            Fantasy (44111)

The category hierarchy is subject to change, and the above example is just a "snapshot" of the categories named "Fantasy" as of this writing.

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 non-leaf categories. 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 field appears as 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.

See Maintaining Category Data for information about how to use the timestamp and version information returned by GetCategories to refresh the locally stored category meta-data after it has been initially downloaded.