{
"openapi": "3.0.0",
"info": {
"title": "Taxonomy API",
"description": "Use the Taxonomy API to discover the most appropriate eBay categories under which sellers can offer inventory items for sale, and the most likely categories under which buyers can browse or search for items to purchase. In addition, the Taxonomy API provides metadata about the required and recommended category aspects to include in listings, and also has two operations to retrieve parts compatibility information.",
"contact": {
"name": "eBay Inc,"
},
"license": {
"name": "eBay API License Agreement",
"url": "https://go.developer.ebay.com/api-license-agreement"
},
"version": "v1.0.1"
},
"servers": [
{
"url": "https://api.ebay.com{basePath}",
"description": "Production",
"variables": {
"basePath": {
"default": "/commerce/taxonomy/v1"
}
}
}
],
"paths": {
"/category_tree/{category_tree_id}/fetch_item_aspects": {
"get": {
"tags": [
"category_tree"
],
"summary": "Get Aspects for All Leaf Categories in a Marketplace",
"description": "This method 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 call to surface changes (new, modified, and removed entities) between an updated version of a bulk downloaded file relative to a previous version.",
"operationId": "fetchItemAspects",
"parameters": [
{
"name": "category_tree_id",
"in": "path",
"description": "The unique identifier of the eBay category tree. The category tree ID for an eBay marketplace can be retrieved using the getDefaultCategoryTreeId method.",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GetCategoriesAspectResponse"
}
}
}
},
"400": {
"description": "Bad Request",
"x-response-codes": {
"errors": {
"62004": {
"domain": "API_TAXONOMY",
"category": "REQUEST",
"description": "The specified category tree ID was not found."
}
}
}
},
"404": {
"description": "Not found"
},
"500": {
"description": "Internal Server Error",
"x-response-codes": {
"errors": {
"62000": {
"domain": "API_TAXONOMY",
"category": "APPLICATION",
"description": "There was a problem with an eBay internal system or process. Contact eBay developer support for assistance."
}
}
}
}
},
"security": [
{
"api_auth": [
"https://api.ebay.com/oauth/api_scope",
"https://api.ebay.com/oauth/api_scope/metadata.insights"
]
}
]
}
},
"/get_default_category_tree_id": {
"get": {
"tags": [
"category_tree"
],
"summary": "Get a Default Category Tree ID",
"description": "A given eBay marketplace might use multiple category trees, but one of those trees is considered to be the default for that marketplace. This call retrieves a reference to the default category tree associated with the specified eBay marketplace ID. The response includes only the tree's unique identifier and version, which you can use to retrieve more details about the tree, its structure, and its individual category nodes.",
"operationId": "getDefaultCategoryTreeId",
"parameters": [
{
"name": "marketplace_id",
"in": "query",
"description": "The unique identifier of the eBay marketplace for which the category tree ID is requested. For a list of supported marketplace IDs, see Marketplaces with Default Category Trees.",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BaseCategoryTree"
}
}
}
},
"204": {
"description": "No content"
},
"400": {
"description": "Bad Request",
"x-response-codes": {
"errors": {
"62002": {
"domain": "API_TAXONOMY",
"category": "REQUEST",
"description": "Missing marketplace ID."
},
"62003": {
"domain": "API_TAXONOMY",
"category": "REQUEST",
"description": "The specified marketplace ID was not found."
}
}
}
},
"500": {
"description": "Internal Server Error",
"x-response-codes": {
"errors": {
"62000": {
"domain": "API_TAXONOMY",
"category": "APPLICATION",
"description": "There was a problem with an eBay internal system or process. Contact eBay developer support for assistance."
}
}
}
}
},
"security": [
{
"api_auth": [
"https://api.ebay.com/oauth/api_scope"
]
}
]
}
},
"/category_tree/{category_tree_id}": {
"get": {
"tags": [
"category_tree"
],
"summary": "Get a Category Tree",
"description": "This method retrieves the complete category tree that is identified by the category_tree_id parameter. The value of category_tree_id was returned by the getDefaultCategoryTreeId method in the categoryTreeId field. The response contains details of all nodes of the specified eBay category tree, as well as the eBay marketplaces that use this category tree.
Note: This method can return a very large payload, so gzip compression is supported. To enable gzip compression, include the Accept-Encoding
header and set its value to gzip
as shown below: Accept-Encoding: gzip
",
"operationId": "getCategoryTree",
"parameters": [
{
"name": "category_tree_id",
"in": "path",
"description": "The unique identifier of the eBay category tree. The category tree ID for an eBay marketplace can be retrieved using the getDefaultCategoryTreeId method.",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "Accept-Encoding",
"in": "header",
"description": "This header indicates the compression-encoding algorithms the client accepts for the response. This value should be set to gzip
.
For more information, refer to HTTP request headers.",
"required": false,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CategoryTree"
}
}
}
},
"400": {
"description": "Bad Request",
"x-response-codes": {
"errors": {
"62004": {
"domain": "API_TAXONOMY",
"category": "REQUEST",
"description": "The specified category tree ID was not found."
}
}
}
},
"404": {
"description": "Not Found"
},
"500": {
"description": "Internal Server Error",
"x-response-codes": {
"errors": {
"62000": {
"domain": "API_TAXONOMY",
"category": "APPLICATION",
"description": "There was a problem with an eBay internal system or process. Contact eBay developer support for assistance."
}
}
}
}
},
"security": [
{
"api_auth": [
"https://api.ebay.com/oauth/api_scope"
]
}
]
}
},
"/category_tree/{category_tree_id}/get_category_subtree": {
"get": {
"tags": [
"category_tree"
],
"summary": "Get a Category Subtree",
"description": "This call retrieves the details of all nodes of the category tree hierarchy (the subtree) below a specified category of a category tree. You identify the tree using the category_tree_id parameter, which was returned by the getDefaultCategoryTreeId call in the categoryTreeId field.
Note: This method can return a very large payload, so gzip compression is supported. To enable gzip compression, include the Accept-Encoding
header and set its value to gzip
as shown below: Accept-Encoding: gzip
",
"operationId": "getCategorySubtree",
"parameters": [
{
"name": "category_id",
"in": "query",
"description": "The unique identifier of the category at the top of the subtree being requested. Metadata on this category and all its descendant categories are retrieved.
Note: If the category_id submitted identifies a leaf node of the tree, the call response will contain information about only that leaf node, which is a valid subtree. ",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "category_tree_id",
"in": "path",
"description": "The unique identifier of the eBay category tree. The category tree ID for an eBay marketplace can be retrieved using the getDefaultCategoryTreeId method.",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "Accept-Encoding",
"in": "header",
"description": "This header indicates the compression-encoding algorithms the client accepts for the response. This value should be set to gzip
.
For more information, refer to HTTP request headers.",
"required": false,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CategorySubtree"
}
}
}
},
"400": {
"description": "Bad Request",
"x-response-codes": {
"errors": {
"62004": {
"domain": "API_TAXONOMY",
"category": "REQUEST",
"description": "The specified category tree ID was not found."
},
"62005": {
"domain": "API_TAXONOMY",
"category": "REQUEST",
"description": "The specified category ID does not belong to the specified category tree."
},
"62006": {
"domain": "API_TAXONOMY",
"category": "REQUEST",
"description": "Missing category ID."
},
"62008": {
"domain": "API_TAXONOMY",
"category": "REQUEST",
"description": "The specified category ID is the root for the category tree. Please use {categoryTreeHref}
to retrieve the entire tree."
}
}
}
},
"404": {
"description": "Not Found"
},
"500": {
"description": "Internal Server Error",
"x-response-codes": {
"errors": {
"62000": {
"domain": "API_TAXONOMY",
"category": "APPLICATION",
"description": "There was a problem with an eBay internal system or process. Contact eBay developer support for assistance."
}
}
}
}
},
"security": [
{
"api_auth": [
"https://api.ebay.com/oauth/api_scope"
]
}
]
}
},
"/category_tree/{category_tree_id}/get_category_suggestions": {
"get": {
"tags": [
"category_tree"
],
"summary": "Get Suggested Categories",
"description": "This call returns an array of category tree leaf nodes in the specified category tree that are considered by eBay to most closely correspond to the query string q. Returned with each suggested node is a localized name for that category (based on the Accept-Language header specified for the call), and details about each of the category's ancestor nodes, extending from its immediate parent up to the root of the category tree.
You identify the tree using the category_tree_id parameter, which was returned by the getDefaultCategoryTreeId call in the categoryTreeId field.
Important: This call is not supported in the Sandbox environment. It will return a response payload in which the categoryName fields contain random or boilerplate text regardless of the query submitted.",
"operationId": "getCategorySuggestions",
"parameters": [
{
"name": "category_tree_id",
"in": "path",
"description": "The unique identifier of the eBay category tree. The category tree ID for an eBay marketplace can be retrieved using the getDefaultCategoryTreeId method.",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "q",
"in": "query",
"description": "A quoted string that describes or characterizes the item being offered for sale. The string format is free form, and can contain any combination of phrases or keywords. eBay will parse the string and return suggested categories for the item.",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CategorySuggestionResponse"
}
}
}
},
"204": {
"description": "No content"
},
"400": {
"description": "Bad Request",
"x-response-codes": {
"errors": {
"62004": {
"domain": "API_TAXONOMY",
"category": "REQUEST",
"description": "The specified category tree ID was not found."
},
"62007": {
"domain": "API_TAXONOMY",
"category": "REQUEST",
"description": "Missing keyword 'q'. Please specify a valid set of keywords that best describes your item."
}
}
}
},
"404": {
"description": "Not found"
},
"500": {
"description": "Internal Server Error",
"x-response-codes": {
"errors": {
"62000": {
"domain": "API_TAXONOMY",
"category": "APPLICATION",
"description": "There was a problem with an eBay internal system or process. Contact eBay developer support for assistance."
}
}
}
}
},
"security": [
{
"api_auth": [
"https://api.ebay.com/oauth/api_scope"
]
}
]
}
},
"/category_tree/{category_tree_id}/get_item_aspects_for_category": {
"get": {
"tags": [
"category_tree"
],
"description": "This call returns a list of aspects that are appropriate or necessary for accurately describing items in the specified leaf category. Each aspect identifies an item attribute (for example, color,) for which the seller will be required or encouraged to provide a value (or variation values) when offering an item in that category on eBay.
For each aspect, getItemAspectsForCategory provides complete metadata, including:
compatibility_property=Trim
and then include the following three name/value filters through one filter parameter: filter=Year:2018,Make:Toyota,Model:Camry
.GET https://api.ebay.com/commerce/
taxonomy/v1/category_tree/100/
get_compatibility_property_values?
category_id=6016&compatibility_property=Trim
&filter=Year:2018,Make:Toyota,Model:Camry
",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "category_id",
"in": "query",
"description": "The unique identifier of an eBay category. This eBay category must be a valid eBay category on the specified eBay marketplace, and the category must support parts compatibility for cars, trucks, or motorcycles.filter=Year:2018
, and multiple compatible vehicle property name/value pairs are delimited with a comma (,).BodyStyle:AWD B9 8W5,C8WD
) you must include a backslash (\\) immediately before the comma to prevent it from being evaluated as a delimiter.compatibility_property=Trim
Year:2022
Make:Audi
Model:A4
BodyStyle:AWD B9 8W5\\,8WD
filter=Year:2022,Make:Audi,Model:A4,BodyStyle:AWD B9 8W5\\,8WD
GET https://api.ebay.com/commerce/
taxonomy/v1/category_tree/100/
get_compatibility_property_values?category_id=6016&compatibility_property=Trim&filter=Year:2022,Make:Audi,Model:A4,BodyStyle:AWD%20B9%208W5%5C%2C8WD
For implementation help, refer to eBay API documentation at https://developer.ebay.com/api-docs/commerce/taxonomy/types/txn:ConstraintFilter",
"required": false,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GetCompatibilityPropertyValuesResponse"
}
}
}
},
"204": {
"description": "No content"
},
"400": {
"description": "Bad Request",
"x-response-codes": {
"errors": {
"62004": {
"domain": "API_TAXONOMY",
"category": "REQUEST",
"description": "The specified category tree ID was not found."
},
"62005": {
"domain": "API_TAXONOMY",
"category": "REQUEST",
"description": "The specified category ID does not belong to specified category tree."
},
"62006": {
"domain": "API_TAXONOMY",
"category": "REQUEST",
"description": "Missing category ID."
},
"62100": {
"domain": "API_TAXONOMY",
"category": "REQUEST",
"description": "The filter format is invalid. For more information, see the API call reference documentation."
},
"62101": {
"domain": "API_TAXONOMY",
"category": "REQUEST",
"description": "This category ID is disabled for parts compatibility."
},
"62102": {
"domain": "API_TAXONOMY",
"category": "REQUEST",
"description": "The compatibility property is invalid."
},
"62103": {
"domain": "API_TAXONOMY",
"category": "REQUEST",
"description": "The CategoryTreeId is not supported."
},
"62104": {
"domain": "API_TAXONOMY",
"category": "REQUEST",
"description": "Missing compatibility property."
}
}
}
},
"404": {
"description": "Not found"
},
"500": {
"description": "Internal Server Error",
"x-response-codes": {
"errors": {
"62000": {
"domain": "API_TAXONOMY",
"category": "APPLICATION",
"description": "There was a problem with an eBay internal system or process. Contact eBay developer support for assistance."
}
}
}
}
},
"security": [
{
"api_auth": [
"https://api.ebay.com/oauth/api_scope"
]
}
]
}
}
},
"components": {
"schemas": {
"AncestorReference": {
"type": "object",
"properties": {
"categoryId": {
"type": "string",
"description": "The unique identifier of the eBay ancestor category.0
. ",
"format": "int32"
}
},
"description": "This type contains information about one of the ancestors of a suggested category. An ordered list of these references describes the path from the suggested category to the root of the category tree it belongs to."
},
"Aspect": {
"type": "object",
"properties": {
"aspectConstraint": {
"description": "Information about the formatting, occurrence, and support of this aspect.",
"$ref": "#/components/schemas/AspectConstraint"
},
"aspectValues": {
"type": "array",
"description": "A list of valid values for this aspect (for example: Red
, Green
, and Blue
), along with any constraints on those values.",
"items": {
"$ref": "#/components/schemas/AspectValue"
}
},
"localizedAspectName": {
"type": "string",
"description": "The localized name of this aspect (for example: Colour
on the eBay UK site). true
indicates that this aspect can be used to help identify item variations."
},
"aspectFormat": {
"type": "string",
"description": "Returned only if the value of aspectDataType identifies a data type that requires specific formatting. Currently, this field provides formatting hints as follows: YYYY
, YYYYMM
, YYYYMMDD
int32
, double
true
indicates that this aspect is required when offering items in the specified category."
},
"aspectUsage": {
"type": "string",
"description": "The enumeration value returned in this field will indicate if the corresponding aspect is recommended or optional.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. For implementation help, refer to eBay API documentation"
},
"expectedRequiredByDate": {
"type": "string",
"description": "The expected date after which the aspect will be required.0
.",
"format": "int32"
},
"relevancy": {
"type": "string",
"description": "This field is reserved for internal or future use."
}
},
"description": "This type contains information about a suggested category tree leaf node that corresponds to keywords provided in the request. It includes details about each of the category's ancestor nodes extending up to the root of the category tree."
},
"CategorySuggestionResponse": {
"type": "object",
"properties": {
"categorySuggestions": {
"type": "array",
"description": "Contains details about one or more suggested categories that correspond to the provided keywords. The array of suggested categories is sorted in order of eBay's confidence of the relevance of each category (the first category is the most relevant).0
. ",
"format": "int32"
},
"childCategoryTreeNodes": {
"type": "array",
"description": "An array of one or more category tree nodes that are the immediate children of the current category tree node, as well as their children, recursively down to the leaf nodes.false
).",
"items": {
"$ref": "#/components/schemas/CategoryTreeNode"
}
},
"leafCategoryTreeNode": {
"type": "boolean",
"description": "A value of true
indicates that the current category tree node is a leaf node (it has no child nodes). A value of false
indicates that the current node has one or more child nodes, which are identified by the childCategoryTreeNodes array.true
."
},
"parentCategoryTreeNodeHref": {
"type": "string",
"description": "The href portion of the getCategorySubtree call that retrieves the subtree below the parent of this category tree node.