eBay Trading APIVersion 1193

GetCategorySpecificsRequestType ( AbstractRequestType )

This is the base request type for the GetCategorySpecifics call. This call is used to retrieve required, recommended, and optional Item Specifics names and values for one or multiple eBay Categories.

Call that uses GetCategorySpecificsRequestType:

Fields



CategoryID ( string ) [0..*]
A unique identifer for an eBay category. Recommended Item Specifics names and values will be retrieved for each eBay category that is specified. Up to 100 CategoryID values may be specified in one call. Although Item Specifics metadata can be retrieved for any eBay category at any level in the hierarchy, it is recommended that users specify leaf category IDs, especially if they are using GetCategorySpecifics to retrieve the Item Specifics applicable to the listing categories they use.

A GetCategorySpecifics call request requires at least one of the following: a CategoryID value, a CategorySpecifics.CategoryID value, or the CategorySpecificsFileInfo field with its value set to true. CategoryID values and CategorySpecific.CategoryID values can both be used in the same request.

Keep in mind that a high number of specified categories can result in longer response times and larger result sets. If your call request happens to time out, you might want specify fewer categories. If any CategoryID values are specified more than once, only the first instance will be used.
See the Field Index to learn which calls use CategoryID.

CategorySpecific ( CategoryItemSpecificsType ) [0..*]
This container can be used instead of, or in conjunction with CategoryID values specified at the call request root level. The CategorySpecific container can actually be more powerful since you can pass in multiple Category ID and Item Specifics name combinations, and if you specify CategoryID values at the root level, only one (Item Specifics) Name value can be used.

A GetCategorySpecifics call request requires at least one of the following: a CategoryID value, a CategorySpecifics.CategoryID value, or the CategorySpecificsFileInfo field with its value set to true. CategoryID values and CategorySpecific.CategoryID values can both be used in the same request.

Keep in mind that a high number of specified categories can result in longer response times and larger result sets. If your call request happens to time out, you might want specify fewer categories. If any CategorySpecifics.CategoryID values are specified more than once, only the first instance will be used.
See the Field Index to learn which calls use CategorySpecific.

CategorySpecificsFileInfo ( boolean ) [0..1]
If this boolean field is included and set to true, the response includes a FileReferenceID and TaskReferenceID value. Use these identifiers as inputs to the downloadFile call in the eBay File Transfer API. That API lets you retrieve a single (bulk) GetCategorySpecifics response with all the Item Specifics recommendations available for the requested site ID. (The downloadFile call downloads a .zip file as an attachment.)

Either the CategorySpecificsFileInfo field or one or more CategoryID and/or CategorySpecific.CategoryID values are required in a GetCategorySpecifics call.

Note: You can use the File Transfer API without using or learning about the Bulk Data Exchange API or other Large Merchant Services APIs.
See the Field Index to learn which calls use CategorySpecificsFileInfo.

ExcludeRelationships ( boolean ) [0..1]
If this boolean field is included and set to true, the Relationship container will not be returned for any Item Specifics name or value recommendations. Relationship recommendations tell you whether an Item Specific has a logical dependency another Item Specific.

For example, in a clothing category, Size Type could be recommended as a parent of Size, because Size=Small would mean something different to buyers depending on whether Size Type=Petite or Size Type=Plus.

In general, it is a good idea to retrieve and use relationship recommendations, as this data can help buyers find the items they want more easily.
See the Field Index to learn which calls use ExcludeRelationships.

IncludeConfidence ( boolean ) [0..1]
If this boolean field is included and set to true, eBay's level of confidence in the popularity of each Item Specific name and value for the specified category is returned in the response. Some sellers may find this useful when choosing whether to use eBay's recommendation or their own Item Specifics names or values.

If this field is used, either one or more CategoryID values and/or one or more CategorySpecific.CategoryID values must be specified. If you try to use this field solely with the CategorySpecificsFileInfo field, the request fails and no TaskReferenceID or FileReferenceID values are returned.
See the Field Index to learn which calls use IncludeConfidence.

LastUpdateTime ( dateTime ) [0..1]
This dateTime filter can be included and used if the user only wants to check for recently-added Item Specifics names and values for one or more categories. If this filter is used, the Item Specifics recommendation engine will only check for Item Specifics names and values that have been added/changed since the date that was passed in to this field. If this field is used, the call will not return any Item Specifics data; it will only return the Recommendations.Updated boolean field for each specified eBay category. A true value in this field will indicate that the recommended Item Specifics names/values for the eBay category have changed since the timestamp passed in the LastUpdateTime field, and a false value in this field will indicate that the recommended Item Specifics names/values for the eBay category have not changed since the timestamp passed in the LastUpdateTime field.

Typically, you will pass in the timestamp value that was returned the last time you refreshed the list of Item Specifics names and values for the same categories. If the Recommendations.Updated flag returns true for any eBay categories in the response, you will want to call GetCategorySpecifics again for those eBay categories to get the latest names and values. As downloading all the data may affect your application's performance, it may help to only download Item Specifics data for an eBay category if the data has changed since you last checked.
See the Field Index to learn which calls use LastUpdateTime.

MaxNames ( int ) [0..1]
This field can be used if you want to control the number of Item Specifics that are returned for each specified eBay category. If you only wanted to retrieve the 10 most popular Item Specifics per category, you would include this field and set its value to 10. Note that mandatory Item Specifics are always returned first in the response. If this field is omitted, all available Item Specifics names for each specified category are returned. If this field's value is set to a value that is higher than the number of Item Specific names available, all Item Specific names are still returned.

Note: In October 2019, eBay updated the GetCategorySpecifics call to retrieve all available Item Specifics name-value pairs for each specified category by default. Previously, 30 Item Specifics names would be returned by default (if the MaxNames filter wasn't used) and 25 corresponding Item Specifics values would be returned by default (if the MaxValuesPerName filter wasn't used). However, if a user wants to limit the number of Item Specifics names and corresponding values that are returned, they can still use the MaxNames and/or MaxValuesPerName filters to do this.
See the Field Index to learn which calls use MaxNames.

MaxValuesPerName ( int ) [0..1]
This field can be used if you want to control the number of corresponding values that are returned for each returned Item Specific name in each specified eBay category. If you only wanted to retrieve the 10 most popular values/options for each returned Item Specific name in each category, you would include this field and set its value to 10. If this field is omitted, all available values for the corresponding Item Specifics name for each category are returned. If this field's value is set to a value that is higher than the number of Item Specific values available for any Item Specific name, all Item Specific values are still returned.

Note: In October 2019, eBay has updated the GetCategorySpecifics call to retrieve all available Item Specifics name-value pairs for each specified category by default. Previously, 30 Item Specifics names would be returned by default (if the MaxNames filter wasn't used) and 25 corresponding Item Specifics values would be returned by default (if the MaxValuesPerName filter wasn't used). However, if a user wants to limit the number of Item Specifics names and corresponding values that are returned, they can still use the MaxNames and/or MaxValuesPerName filters to do this.
See the Field Index to learn which calls use MaxValuesPerName.

Name ( string ) [0..1]
This field can be used if you already have an Item Specific name in mind, and you only want the recommended values for this Item Specifics name. If you specify multiple eBay categories in the request, the recommendation engine may find a matching Item Specifics name for some categories, but not for others. For eBay categories where the Item Specifics name is not found, recommended Item Specifics names and values will be returned. The Item Specifics name passed in this field is case-sensitive, and wildcards are not supported.

See the Field Index to learn which calls use Name.