GET/category_tree/{category_tree_id}/get_category_suggestions
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.
Input
Resource URI
This method is not supported in Sandbox environment.
URI parameters
| Parameter | Type | Description |
|---|---|---|
| category_tree_id | string | The unique identifier of the eBay category tree. The category tree ID for an eBay marketplace can be retrieved using the getDefaultCategoryTreeId method. Occurrence: Required |
| 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. Occurrence: Required |
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.
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.
Request payload
This call has no payload.
Request fields
This call has no field definitions.
Output
HTTP response headers
This call has no response headers.
Response payload
Response fields
| Output container/field | Type | Description |
|---|---|---|
| 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). Occurrence: Always |
| categorySuggestions.category | Category | Contains details about the suggested category. Occurrence: Always |
| categorySuggestions.category.categoryId | string | The unique identifier of the eBay category within its category tree. Occurrence: Always |
| categorySuggestions.category.categoryName | string | The name of the category identified by categoryId. Occurrence: Always |
| 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. Occurrence: Always |
| categorySuggestions.categoryTreeNodeAncestors.categoryId | string | The unique identifier of the eBay ancestor category. Occurrence: Always |
| categorySuggestions.categoryTreeNodeAncestors.categoryName | string | The name of the ancestor category identified by categoryId. Occurrence: Always |
| categorySuggestions.categoryTreeNodeAncestors.categorySubtreeNodeHref | string | The href portion of the getCategorySubtree call that retrieves the subtree below the ancestor category node. Occurrence: Always |
| categorySuggestions.categoryTreeNodeAncestors.categoryTreeNodeLevel | integer | The absolute level of the ancestor category node in the hierarchy of its category tree. Occurrence: Always |
| categorySuggestions.categoryTreeNodeLevel | integer | The absolute level of the category tree node in the hierarchy of its category tree. Occurrence: Always |
| categorySuggestions.relevancy | string | This field is reserved for internal or future use. Occurrence: NA |
| categoryTreeId | string | The unique identifier of the eBay category tree from which suggestions are returned. Occurrence: Always |
| categoryTreeVersion | string | 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. 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.
| Status | Meaning |
|---|---|
| 200 | Success |
| 204 | No content |
| 400 | Bad Request |
| 404 | Not found |
| 500 | Internal Server Error |
Error codes
For more on errors, plus the codes of other common errors, see Handling errors.
| Code | Domain | Category | Meaning |
|---|---|---|---|
| 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. |
Warnings
This call has no 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: Get category suggestions for a product
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.
Input
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.
GEThttps://api.ebay.com/commerce/taxonomy/v1/category_tree/0/get_category_suggestions?q=iphone
Output
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.