Skip to main content

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

GET https://api.ebay.com/commerce/taxonomy/v1/category_tree/{category_tree_id}/get_category_suggestions?

This method is not supported in Sandbox environment.

URI parameters

ParameterTypeDescription
category_tree_idstringThe unique identifier of the eBay category tree. The category tree ID for an eBay marketplace can be retrieved using the getDefaultCategoryTreeId method.

Occurrence: Required

qstringA 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/fieldTypeDescription
categorySuggestionsarray 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).

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.

Occurrence: Always

categorySuggestions.categoryCategory

Contains details about the suggested category.

Occurrence: Always

categorySuggestions.category.categoryIdstring

The 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

categorySuggestions.category.categoryNamestring

The name of the category identified by categoryId.

Occurrence: Always

categorySuggestions.categoryTreeNodeAncestorsarray 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.

Note: The root node of a full default category tree includes categoryId and categoryName fields, but their values should not be relied upon. They provide no useful information for application development.

Occurrence: Always

categorySuggestions.categoryTreeNodeAncestors.categoryIdstring

The unique identifier of the eBay ancestor category.

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

categorySuggestions.categoryTreeNodeAncestors.categoryNamestring

The name of the ancestor category identified by categoryId.

Occurrence: Always

categorySuggestions.categoryTreeNodeAncestors.categorySubtreeNodeHrefstring

The href portion of the getCategorySubtree call that retrieves the subtree below the ancestor category node.

Occurrence: Always

categorySuggestions.categoryTreeNodeAncestors.categoryTreeNodeLevelinteger

The absolute level of the ancestor category node in the hierarchy of its category tree.

Note: The root node of any full category tree is always at level 0.

Occurrence: Always

categorySuggestions.categoryTreeNodeLevelinteger

The absolute level of the category tree node in the hierarchy of its category tree.

Note: The root node of any full category tree is always at level 0.

Occurrence: Always

categorySuggestions.relevancystring

This field is reserved for internal or future use.

Occurrence: NA

categoryTreeIdstring

The unique identifier of the eBay category tree from which suggestions are returned.

Occurrence: Always

categoryTreeVersionstring

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.

StatusMeaning
200Success
204No content
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.
62007API_TAXONOMYREQUESTMissing 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.