Changes since
the last release

com.ebay.sdk.call
Class GetCategorySpecificsCall

java.lang.Object
  extended by com.ebay.sdk.ApiCall
      extended by com.ebay.sdk.call.GetCategorySpecificsCall

public class GetCategorySpecificsCall
extends ApiCall

Wrapper class of the GetCategorySpecifics call of eBay SOAP API.

Title: SOAP API wrapper library.

Description: Contains wrapper classes for eBay SOAP APIs.

Copyright: Copyright (c) 2009

Company: eBay Inc.


Input property: CategoryID - A unique identifer for an eBay leaf-level 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.

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.
Input property: LastUpdateTime - 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.
Input property: MaxNames - 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 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.

Input property: MaxValuesPerName - 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.

Input property: Name - 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.


Input property: CategorySpecific - 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.
Input property: ExcludeRelationships - 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.
Input property: IncludeConfidence - 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.
Input property: CategorySpecificsFileInfo - 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.
Output property: ReturnedRecommendations - This container provide details about relevant Item Specifics for the specified category. Required Item Specifics are generally returned at the top of the response payload, followed by the other most common/popular Item Specifics for the category. If an Item Specific is required, a MinValues field will be returned with a value of 1, and the corresponding UsageConstraint field will show a value of Required. Optional Item Specifics are returned after required and recommended Item Specifics, but sellers should still provide any optional Item Specific name-value pairs if known and relevant for the product.

As mentioned above, the most relevant Item Specifics are returned first, and similarly, if an Item Specific has multiple suggested values, these values are sorted according to popularity (most popular to less popular/common).

This node returns empty (or it's not returned) for a category if there is no applicable data (such as when you request a parent category, a category that has no popular Item Specifics yet, or a duplicate category that was already returned). If you pass in the CategoryID and Name fields together, but no matching values are found for the name, eBay returns the name with no values (even if the name is not recommended).

If GetCategoryFeatures indicates that Item Specifics are enabled for a leaf category, but GetCategorySpecifics doesn't return any recommendations for that category, the seller can still specify their own Item Specifics in that category.
Output property: ReturnedTaskReferenceID - A TaskReferenceID and a FileReferenceID value are returned if the CategorySpecificsFileInfo field is included in the call request and set to true. These values will be used as inputs in the downloadFile call of the 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.)
Output property: ReturnedFileReferenceID - A TaskReferenceID and a FileReferenceID value are returned if the CategorySpecificsFileInfo field is included in the call request and set to true. These values will be used as inputs in the downloadFile call of the 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.)

Version:
1.0
Author:
Ron Murphy

Field Summary
 
Fields inherited from class com.ebay.sdk.ApiCall
apiException, sendReqListeners
 
Constructor Summary
GetCategorySpecificsCall()
          Constructor.
GetCategorySpecificsCall(ApiContext apiContext)
          Constructor.
 
Method Summary
 java.lang.String[] getCategoryID()
          Gets the GetCategorySpecificsRequestType.categoryID.
 CategoryItemSpecificsType[] getCategorySpecific()
          Gets the GetCategorySpecificsRequestType.categorySpecific.
 RecommendationsType[] getCategorySpecifics()
          This is the base request type for the GetCategorySpecifics call.
 java.lang.Boolean getCategorySpecificsFileInfo()
          Gets the GetCategorySpecificsRequestType.categorySpecificsFileInfo.
 java.lang.Boolean getExcludeRelationships()
          Gets the GetCategorySpecificsRequestType.excludeRelationships.
 java.lang.Boolean getIncludeConfidence()
          Gets the GetCategorySpecificsRequestType.includeConfidence.
 java.util.Calendar getLastUpdateTime()
          Gets the GetCategorySpecificsRequestType.lastUpdateTime.
 java.lang.Integer getMaxNames()
          Gets the GetCategorySpecificsRequestType.maxNames.
 java.lang.Integer getMaxValuesPerName()
          Gets the GetCategorySpecificsRequestType.maxValuesPerName.
 java.lang.String getName()
          Gets the GetCategorySpecificsRequestType.name.
 java.lang.String getReturnedFileReferenceID()
          Valid after executing the API.
 RecommendationsType[] getReturnedRecommendations()
          Valid after executing the API.
 java.lang.String getReturnedTaskReferenceID()
          Valid after executing the API.
 void setCategoryID(java.lang.String[] categoryID)
          Sets the GetCategorySpecificsRequestType.categoryID.
 void setCategorySpecific(CategoryItemSpecificsType[] categorySpecific)
          Sets the GetCategorySpecificsRequestType.categorySpecific.
 void setCategorySpecificsFileInfo(java.lang.Boolean categorySpecificsFileInfo)
          Sets the GetCategorySpecificsRequestType.categorySpecificsFileInfo.
 void setExcludeRelationships(java.lang.Boolean excludeRelationships)
          Sets the GetCategorySpecificsRequestType.excludeRelationships.
 void setIncludeConfidence(java.lang.Boolean includeConfidence)
          Sets the GetCategorySpecificsRequestType.includeConfidence.
 void setLastUpdateTime(java.util.Calendar lastUpdateTime)
          Sets the GetCategorySpecificsRequestType.lastUpdateTime.
 void setMaxNames(java.lang.Integer maxNames)
          Sets the GetCategorySpecificsRequestType.maxNames.
 void setMaxValuesPerName(java.lang.Integer maxValuesPerName)
          Sets the GetCategorySpecificsRequestType.maxValuesPerName.
 void setName(java.lang.String name)
          Sets the GetCategorySpecificsRequestType.name.
 
Methods inherited from class com.ebay.sdk.ApiCall
addDetailLevel, addSendRequestListener, execute, executeByApiName, getApiContext, getApiException, getBotBlock, getCallRetry, getDetailLevel, getEnableCompression, getEndUserIP, getErrorHandling, getInvocationID, getMessageID, getOutputSelector, getRequestXml, getResponseObject, getResponseXml, getSite, getWarningLevel, hasError, hasWarning, isEnableoAuthTokenHTTPHeader, removeSendRequestListener, setApiContext, setBotBlock, setCallRetry, setDetailLevel, setEnableCompression, setEnableoAuthTokenHTTPHeader, setEndUserIP, setErrorHandling, setInvocationID, setMessageID, setOutputSelector, setSite, setWarningLevel
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

GetCategorySpecificsCall

public GetCategorySpecificsCall()
Constructor.


GetCategorySpecificsCall

public GetCategorySpecificsCall(ApiContext apiContext)
Constructor.

Parameters:
apiContext - The ApiContext object to be used to make the call.
Method Detail

getCategorySpecifics

public RecommendationsType[] getCategorySpecifics()
                                           throws ApiException,
                                                  SdkException,
                                                  java.lang.Exception
This is the base request type for the GetCategorySpecifics call. This call is used to retrieve recommended Item Specifics names and values for one or multiple eBay Categories.

Returns:
The RecommendationsType[] object.
Throws:
ApiException
SdkException
java.lang.Exception

getCategoryID

public java.lang.String[] getCategoryID()
Gets the GetCategorySpecificsRequestType.categoryID.

Returns:
String[]

setCategoryID

public void setCategoryID(java.lang.String[] categoryID)
Sets the GetCategorySpecificsRequestType.categoryID.

Parameters:
categoryID - String[]

getCategorySpecific

public CategoryItemSpecificsType[] getCategorySpecific()
Gets the GetCategorySpecificsRequestType.categorySpecific.

Returns:
CategoryItemSpecificsType[]

setCategorySpecific

public void setCategorySpecific(CategoryItemSpecificsType[] categorySpecific)
Sets the GetCategorySpecificsRequestType.categorySpecific.

Parameters:
categorySpecific - CategoryItemSpecificsType[]

getCategorySpecificsFileInfo

public java.lang.Boolean getCategorySpecificsFileInfo()
Gets the GetCategorySpecificsRequestType.categorySpecificsFileInfo.

Returns:
Boolean

setCategorySpecificsFileInfo

public void setCategorySpecificsFileInfo(java.lang.Boolean categorySpecificsFileInfo)
Sets the GetCategorySpecificsRequestType.categorySpecificsFileInfo.

Parameters:
categorySpecificsFileInfo - Boolean

getExcludeRelationships

public java.lang.Boolean getExcludeRelationships()
Gets the GetCategorySpecificsRequestType.excludeRelationships.

Returns:
Boolean

setExcludeRelationships

public void setExcludeRelationships(java.lang.Boolean excludeRelationships)
Sets the GetCategorySpecificsRequestType.excludeRelationships.

Parameters:
excludeRelationships - Boolean

getIncludeConfidence

public java.lang.Boolean getIncludeConfidence()
Gets the GetCategorySpecificsRequestType.includeConfidence.

Returns:
Boolean

setIncludeConfidence

public void setIncludeConfidence(java.lang.Boolean includeConfidence)
Sets the GetCategorySpecificsRequestType.includeConfidence.

Parameters:
includeConfidence - Boolean

getLastUpdateTime

public java.util.Calendar getLastUpdateTime()
Gets the GetCategorySpecificsRequestType.lastUpdateTime.

Returns:
Calendar

setLastUpdateTime

public void setLastUpdateTime(java.util.Calendar lastUpdateTime)
Sets the GetCategorySpecificsRequestType.lastUpdateTime.

Parameters:
lastUpdateTime - Calendar

getMaxNames

public java.lang.Integer getMaxNames()
Gets the GetCategorySpecificsRequestType.maxNames.

Returns:
Integer

setMaxNames

public void setMaxNames(java.lang.Integer maxNames)
Sets the GetCategorySpecificsRequestType.maxNames.

Parameters:
maxNames - Integer

getMaxValuesPerName

public java.lang.Integer getMaxValuesPerName()
Gets the GetCategorySpecificsRequestType.maxValuesPerName.

Returns:
Integer

setMaxValuesPerName

public void setMaxValuesPerName(java.lang.Integer maxValuesPerName)
Sets the GetCategorySpecificsRequestType.maxValuesPerName.

Parameters:
maxValuesPerName - Integer

getName

public java.lang.String getName()
Gets the GetCategorySpecificsRequestType.name.

Returns:
String

setName

public void setName(java.lang.String name)
Sets the GetCategorySpecificsRequestType.name.

Parameters:
name - String

getReturnedFileReferenceID

public java.lang.String getReturnedFileReferenceID()
Valid after executing the API. Gets the returned GetCategorySpecificsResponseType.returnedFileReferenceID.

Returns:
String

getReturnedRecommendations

public RecommendationsType[] getReturnedRecommendations()
Valid after executing the API. Gets the returned GetCategorySpecificsResponseType.returnedRecommendations.

Returns:
RecommendationsType[]

getReturnedTaskReferenceID

public java.lang.String getReturnedTaskReferenceID()
Valid after executing the API. Gets the returned GetCategorySpecificsResponseType.returnedTaskReferenceID.

Returns:
String

Changes since
the last release

The information contained in this document is proprietary and confidential. Use of this information and the eBay API requires a Non-Disclosure Agreement (NDA) between the user and eBay Inc. For information regarding a qualifying NDA, contact Developer Relations: developer-relations@ebay.com
© 2004-2009 eBay Inc. All rights reserved.