Retrieves full information about all categories that are children of the category ID you pass in. If you want to get all of the base level categories for Bonanza, pass in category ID "0". If you need a full database dump of all categories, you can email our API address (api -at- and we can send you one.

Take a look at some examples in C#, Java, PHP, Python, and Ruby.

getCategories Input

getCategories is a non-secure request with the following URL and HTTP header requirements:

Submit to URL:
Required in HTTP header: X-BONANZLE-API-DEV-NAME set to your dev_id

The name for your request should be getCategoriesRequest.

So, for example, here is the Ruby code to submit your request:

# Open connection to over port 80
http ="")
  "/api_requests/standard_request", # The path we're posting to
  "getCategoriesRequest=your_serialized_JSON_data", # The data being posted
  { 'X-BONANZLE-API-DEV-NAME' => 'abcdef123456' } # The HTTP header, which gives your dev_id

Here are the available input parameters that can be serialized into JSON:

Argument Type Occurrence Meaning
Call-specific Input Fields
categoryParent integer Required The numeric ID of the parent category whose child categories you want to grab. To grab the lowest level categories (which technically have no parent), use category ID 0.

getCategories Output

The name for the output returned from this request is getCategoriesResponse. So, after parsing the serialized response into JSON, you can access the data with something like:


Here are all the possible output parameters:

Argument Type Occurrence Meaning
Standard Output Fields
errorMessage Container Conditionally Description of an error or warning that occurred when Bonanza processed the request. Not returned if the ack value is Success.
errorMessage.error Container Conditionally,
repeatable: [0..*]
errorMessage.error.category ErrorCategory Conditionally Currently unused.
errorMessage.error.message string Conditionally A description of the error
errorMessage.error.type ErrorType Conditionally A unique descriptive name for the error.
timestamp dateTime Always This value represents the date and time when Bonanza processed the request. The time zone of this value is GMT and the format is the ISO 8601 date and time format (YYYY-MM-DDTHH:MM:SS.SSSZ). See the "dateTime" type for information about this time format and converting to and from the GMT time zone.
warnings Container Conditionally Description of a warning that occurred when Bonanza processed the request.
warnings.unrecognized_parameters Container Conditionally,
repeatable: [0..*]
An array of unrecognized parameters.
Call-specific Output Fields
categoryArray   Always Contains an array of the categories that were children of your parentCategory
categoryArray.categoryBriefName string Always The name for only this category, i.e., "Collectibles" or "Electronics." To get the category's name as part of its hierarchy, see categoryArray.categoryName.
categoryArray.categoryId integer Always The ID for this category
categoryArray.categoryLevel integer Always The depth of this category. Base categories (with no parents) are level one, their children are level two, and so on. The deepest Bonanza categories are level five.
categoryArray.categoryName string Always The full name of this category, i.e., "Collectibles >> Decorative Collectibles >> Figurines". See also categoryArray.categoryBriefName.
categoryArray.traitCount integer Always The number of item traits ("item specifics", in eBay parlance) available for this category. For example, "material," "size," "color," etc. To retrieve these traits, use getCategoryTraits.

getCategories Examples