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.
Note: This call can return a large payload, so you are advised to submit the request with the following HTTP header:
With this header (in addition to the required headers described under HTTP Request Headers), the call returns the response with gzip compression.
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.
This method is not supported in Sandbox environment.
|category_tree_id||string||The unique identifier of the eBay category tree for which suggested nodes are being requested. |
|q||string||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. |
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.
This call has no payload.
This call has no field definitions.
This call has no response headers.
|categorySuggestions||array of CategorySuggestion|
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).
Contains details about the suggested category.
The unique identifier of the eBay category within its category tree.
The name of the category identified by categoryId.
|categorySuggestions.categoryTreeNodeAncestors||array of AncestorReference|
An ordered list of category references that describes the location of the suggested category in the specified category tree. The list identifies the category's ancestry as a sequence of parent nodes, from the current node's immediate parent to the root node of the category tree.
The unique identifier of the eBay ancestor category.
The name of the ancestor category identified by categoryId.
The href portion of the getCategorySubtree call that retrieves the subtree below the ancestor category node.
The absolute level of the ancestor category node in the hierarchy of its category tree.
The absolute level of the category tree node in the hierarchy of its category tree.
This field is reserved for internal or future use.
The unique identifier of the eBay category tree from which suggestions are returned.
The version of the category tree identified by categoryTreeId. It's a good idea to cache this value for comparison so you can determine if this category tree has been modified in subsequent calls.
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.|
|62007||API_TAXONOMY||REQUEST||Missing keyword 'q'. Please specify a valid set of keywords that best describes your item.|
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.
This sample retrieves an array of categories selected from the specified category tree which are considered by eBay to most closely correspond to the query string provided.
Use the category_tree_id path parameter to specify the category tree, and use the q query parameter to provide a free form string of search terms related to the product for which you want category suggestions.
A successful call returns an array of categories, each one accompanied by details about each of the category's ancestor nodes, extending from its immediate parent up to the root of the category tree.