This call returns a complete list of aspects for all of the leaf categories that belong to an eBay marketplace. The eBay marketplace is specified through the category_tree_id URI parameter.
Note: A successful call returns a payload as a gzipped JSON file sent as a binary file using the content-type:application/octet-stream in the response. This file may be large (over 100 MB, compressed). Extract the JSON file from the compressed file with a utility that handles .gz or .gzip. The open source Taxonomy SDK can be used to compare the aspect metadata that is returned in this response. The Taxonomy SDK uses this method to surface changes (new, modified, and removed entities) between an updated version of a bulk downloaded file relative to a previous version.
This method is supported in Sandbox environment. To access the endpoint, just replace the
api.ebay.com root URI with
|category_tree_id||string||The unique identifier of the eBay category tree being requested. |
HTTP request headers
All requests made to eBay REST operations require you to provide the
Authorization HTTP header for authentication authorization.
All other standard RESTful request headers are optional. For more information on standard RESTful request headers, see the HTTP request headers- opens rest request components page table.
This request requires an access token created with the client credentials grant flow, using one or more scopes from the following list (please check your Application Keys page for a list of OAuth scopes available to your application):
See OAuth access tokens for more information.
Note: The metadata.insights scope is conditional and is based on the App Check to gain access to the 'Buyer Demand Data'. Please refer to relevanceIndicator.
This call has no payload.
This call has no field definitions.
HTTP response headers
This call has no response headers.
Important: The response for this call is always a JSON GZIP file. The response is shown as JSON fields so that they can be explained.
The unique identifier of the eBay category tree being requested.
The version of the category tree that is returned in the categoryTreeId field.
|categoryAspects||array of CategoryAspect|
An array of aspects that are appropriate or necessary for accurately describing items in a particular leaf category.
The details that are appropriate or necessary to accurately define the category.
The unique identifier of the eBay category within its category tree.
The name of the category identified by categoryId.
|categoryAspects.aspects||array of Aspect|
A list of aspect metadata that is used to describe the items in a particular leaf category.
Information about the formatting, occurrence, and support of this aspect.
|categoryAspects.aspects.aspectConstraint.aspectApplicableTo||array of AspectApplicableToEnum|
This value indicate if the aspect identified by the aspects.localizedAspectName field is a product aspect (relevant to catalog products in the category) or an item/instance aspect, which is an aspect whose value will vary based on a particular instance of the product.
The data type of this aspect.
A value of
Returned only if the value of aspectDataType identifies a data type that requires specific formatting. Currently, this field provides formatting hints as follows:
The maximum length of the item/instance aspect's value. The seller must make sure not to exceed this length when specifying the instance aspect's value for a product. This field is only returned for instance aspects.
The manner in which values of this aspect must be specified by the seller (as free text or by selecting from available options).
A value of
The enumeration value returned in this field will indicate if the corresponding aspect is recommended or optional.
The expected date after which the aspect will be required.
Indicates whether this aspect can accept single or multiple values for items in the specified category.
|categoryAspects.aspects.aspectValues||array of AspectValue|
A list of valid values for this aspect (for example:
The localized value of this aspect.
|categoryAspects.aspects.aspectValues.valueConstraints||array of ValueConstraint|
Not returned if the value of the localizedValue field can always be selected for this aspect of the specified category.
The name of the control aspect on which the current aspect value depends.
|categoryAspects.aspects.aspectValues.valueConstraints.applicableForLocalizedAspectValues||array of string|
Contains a list of the values of the control aspect on which this aspect's value depends. When the control aspect has any of the specified values, the current value of the current aspect will also be available.
The localized name of this aspect (for example:
The relevance of this aspect. This field is returned if eBay has data on how many searches have been performed for listings in the category using this item aspect.
The number of recent searches (based on 30 days of data) for the aspect.
HTTP status codes
This call can return one of the following HTTP status codes. For an overview of the status codes, see HTTP status codes in Using eBay RESTful APIs.
|500||Internal Server Error|
For more on errors, plus the codes of other common errors, see Handling errors.
|62000||API_TAXONOMY||APPLICATION||There was a problem with an eBay internal system or process. Contact eBay developer support for assistance.|
|62004||API_TAXONOMY||REQUEST||The specified category tree ID was not found.|
This call has no warnings.
New to making API calls? Please see Making a Call.
Note: Identifiers, such as order IDs or user IDs, and personal data in these samples might be anonymized or may no longer be active on eBay. If necessary, substitute current, relevant eBay data in your requests.
Sample 1: Fetch Item Aspects for a Marketplace
This sample retrieves the item aspects for the specified eBay marketplace.
The category_tree_id value is passed as a path parameter, and this value identifies the eBay marketplace.
The output is an HTTP status. If the call is successful, the gzipped JSON file containing the item aspects for the specified eBay marketplace is downloaded.