taxonomy APIv1_beta.1.0

getCategorySuggestions

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.

Note: This call can return a large payload, so you are advised to submit the request with the following HTTP header:

  Accept-Encoding: application/gzip

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.

Input

Resource URI (production)

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

URI parameters

ParameterTypeDescription
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

category_tree_idstringThe unique identifier of the eBay category tree for which suggested nodes are being requested.

Occurrence: Required

HTTP request headers

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

OAuth scope

This request requires an Application access token with the following scope(s):

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

See Oauth access tokens for more information.

Output

HTTP response headers

Output container/fieldTypeDescription
categorySuggestionsarray of CategorySuggestionContains 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.categoryCategoryContains details about the suggested category.

Occurrence: Always

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

categorySuggestions.category.categoryNamestringThe canonical name of the category identified by categoryId.

Note: Don't depend on category names to be unique within a given category tree.

Occurrence: Always

categorySuggestions.categoryTreeNodeAncestorsarray of AncestorReferenceAn 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.categoryIdstringThe 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.categoryNamestringThe canonical name of the ancestor category identified by categoryId.

Note: Don't depend on category names to be unique within a given category tree.

Occurrence: Always

categorySuggestions.categoryTreeNodeAncestors.categorySubtreeNodeHrefstringThe href portion of the getCategorySubtree call that retrieves the subtree below the ancestor category node.

Occurrence: Always

categorySuggestions.categoryTreeNodeAncestors.categoryTreeNodeLevelintegerThe 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.categoryTreeNodeLevelintegerThe 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.relevancystringThis field is reserved for internal or future use.

Occurrence: NA

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

Occurrence: Always

categoryTreeVersionstringThe 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

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.

Samples

New to making API calls? Please see Making a Call.

Note: Some item IDs, user IDs, or other data in these samples might no longer be active on eBay. If necessary, you can substitute current 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.
GET
https://api.ebay.com/commerce/taxonomy/v1_beta/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.