taxonomy APIv1_beta.6.0

fetchItemAspects

GET
/category_tree/{category_tree_id}/fetch_item_aspects
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: This call can return a large payload, so the call returns the response as a gzipped JSON file. The open source Taxonomy SDK can be used to compare the aspect metadata that is returned in this response. The bulk download capability that this method provides, when combined with the Taxonomy SDK, brings transparency to the evolution of the metadata.

Input

Resource URI (production)

GET https://api.ebay.com/commerce/taxonomy/v1_beta/category_tree/{category_tree_id}/fetch_item_aspects

URI parameters

ParameterTypeDescription
category_tree_idstringThe unique identifier of the eBay category tree being requested.

Occurrence: Required

HTTP request headers

All requests made to eBay REST operations require you to provide the Authorization HTTP header for authentication authorization.

OAuth scope

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

https://api.ebay.com/oauth/api_scope

See OAuth access tokens for more information.

Output

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

Output container/fieldTypeDescription
categoryTreeIdstringThe unique identifier of the eBay category tree being requested.

Occurrence: Always

categoryTreeVersionstringThe version of the category tree that is returned in the categoryTreeId field.

Occurrence: Always

categoryAspectsarray of CategoryAspectAn array of aspects that are appropriate or necessary for accurately describing items in a particular leaf category.

Occurrence: Always

categoryAspects.categoryCategoryThe details that are appropriate or necessary to accurately define the category.

Occurrence: Always

categoryAspects.category.categoryIdstringThe unique identifier of the eBay category within its category tree.

Note: The root node of a full default category tree includes the categoryId field, but its value should not be relied upon. It provides no useful information for application development.

Occurrence: Always

categoryAspects.category.categoryNamestringThe name of the category identified by categoryId.

Occurrence: Always

categoryAspects.aspectsarray of AspectA list of aspect metadata that is used to describe the items in a particular leaf category.

Occurrence: Conditional

categoryAspects.aspects.aspectConstraintAspectConstraintInformation about the formatting, occurrence, and support of this aspect.

Occurrence: Always

categoryAspects.aspects.aspectConstraint.aspectApplicableToarray of AspectApplicableToEnumThis 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.

Occurrence: Conditional

categoryAspects.aspects.aspectConstraint.aspectDataTypeAspectDataTypeEnumThe data type of this aspect.

Occurrence: Always

categoryAspects.aspects.aspectConstraint.aspectEnabledForVariationsbooleanA value of true indicates that this aspect can be used to help identify item variations.

Occurrence: Always

categoryAspects.aspects.aspectConstraint.aspectFormatstringReturned only if the value of aspectDataType identifies a data type that requires specific formatting. Currently, this field provides formatting hints as follows:
  • DATE: YYYY, YYYYMM, YYYYMMDD
  • NUMBER: int32, double

Occurrence: Conditional

categoryAspects.aspects.aspectConstraint.aspectMaxLengthintegerThe 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.

Occurrence: Conditional

categoryAspects.aspects.aspectConstraint.aspectModeAspectModeEnumThe manner in which values of this aspect must be specified by the seller (as free text or by selecting from available options).

Occurrence: Always

categoryAspects.aspects.aspectConstraint.aspectRequiredbooleanA value of true indicates that this aspect is required when offering items in the specified category.

Occurrence: Always

categoryAspects.aspects.aspectConstraint.aspectUsageAspectUsageEnumThe enumeration value returned in this field will indicate if the corresponding aspect is recommended or optional.

Note: This field is always returned, even for hard-mandated/required aspects (where aspectRequired: true). The value returned for required aspects will be RECOMMENDED, but they are actually required and a seller will be blocked from listing or revising an item without these aspects.

Occurrence: Always

categoryAspects.aspects.aspectConstraint.expectedRequiredByDatestringThe expected date after which the aspect will be required.

Note: The value returned in this field specifies only an approximate date, which may not reflect the actual date after which the aspect is required.

Occurrence: Conditional

categoryAspects.aspects.aspectConstraint.itemToAspectCardinalityItemToAspectCardinalityEnumIndicates whether this aspect can accept single or multiple values for items in the specified category.

Occurrence: Always

categoryAspects.aspects.aspectValuesarray of AspectValueA list of valid values for this aspect (for example: Red, Green, and Blue), along with any constraints on those values.

Occurrence: Always

categoryAspects.aspects.aspectValues.localizedValuestringThe localized value of this aspect.

Note: This value is always localized for the specified marketplace.

Occurrence: Always

categoryAspects.aspects.aspectValues.valueConstraintsarray of ValueConstraintNot returned if the value of the localizedValue field can always be selected for this aspect of the specified category.

Contains a list of the dependencies that identify when the value of the localizedValue field is available for the current aspect. Each dependency specifies the values of another aspect of the same category (a control aspect), for which the current value of the current aspect can also be selected by the seller.

Example: A shirt is available in three sizes and three colors, but only the Small and Medium sizes come in Green. Thus for the Color aspect, the value Green is constrained by its dependency on Size (the control aspect). Only when the Size aspect value is Small or Medium, can the Color aspect value of Green be selected by the seller.

Occurrence: Conditional

categoryAspects.aspects.aspectValues.valueConstraints.applicableForLocalizedAspectNamestringThe name of the control aspect on which the current aspect value depends.

Occurrence: Conditional

categoryAspects.aspects.aspectValues.valueConstraints.applicableForLocalizedAspectValuesarray of stringContains 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.

Occurrence: Conditional

categoryAspects.aspects.localizedAspectNamestringThe localized name of this aspect (for example: Colour on the eBay UK site).

Note: This name is always localized for the specified marketplace.

Occurrence: Always

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.

StatusMeaning
200Success
400Bad Request
404Not found
500Internal Server Error

Error codes

For more on errors, plus the codes of other common errors, see Handling errors.

CodeDomainCategoryMeaning
62000API_TAXONOMYAPPLICATIONThere was a problem with an eBay internal system or process. Contact eBay developer support for assistance.
62004API_TAXONOMYREQUESTThe specified category tree ID was not found.

Warnings

Samples

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.

Input

The category_tree_id value is passed as a path parameter, and this value identifies the eBay marketplace.
GET
https://api.ebay.com/commerce/taxonomy/v1_beta/category_tree/0/fetch_item_aspects

Output

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.