Retrieving Category-to-Meta-Data Mappings

This section discusses the means and strategies for determining which categories on a given eBay site support Item Specifics and Pre-filled Item Information.

In order for a seller to be able to specify Item Specifics or Pre-filled Item Information for a particular item, the item must be associated with a category that supports these features. You determine the availability of these features for a given category by using GetCategory2CSCall. This call retrieves a list of category-to-characteristic set mappings. These mappings indicate whether or not a given category supports these features, and they provide additional information that you use as input to other calls. If a category supports Item Specifics, it is considered to be attributes-enabled and it is mapped to a characteristic set. If a category supports Pre-filled Item Information, it is considered to be catalog-enabled and it is mapped to a product search page, a product finder, or both.

The eBay SDK for .NET's Attributes Library includes a sample data-source provider called CategoryCSDownloader, which executes GetCategory2CSCall and handles other common functionality that you need when working with meta-data mappings. This class implements the ICategoryCSProvider interface and caches the data in memory. If you want to use the Attributes Library, you can use the sample downloader class or you can create your own implementation of the ICategoryCSProvider interface that stores the data in a different way (such as a database).

GetCategory2CSCall does not retrieve other information about the category hierarchy, such as parent/child category relationships. Therefore, you need to use the mapping information in combination with the GetCategoriesCall response to present a list of categories to the user. You can use visual cues to indicate which categories support Item Specifics and which ones support Pre-filled Item Information. Or, you might choose not to provide such visual cues, and instead just use the mappings to determine whether or not to render the Item Specifics form or to offer the seller different listing options (see Overview of Implementing eBay Listing Options).

GetCategory2CSCall retrieves data that maps each attributes-enabled category to zero or one full characteristic sets. On some sites, it also indicates which categories support site-wide characteristic sets. Thus, for a given category, there can be:

No characteristic sets
One full characteristic set
One or more site-wide characteristic sets
One full characteristic set and one or more site-wide characteristic sets

On certain sites, many categories support site-wide characteristic sets. Therefore, to reduce the size of the response:

The GetCategory2CSCall response indicates only those categories that do not support site-wide characteristic sets.

Instead of repeating this information for each category, a separate SiteWideCharacteristicSets node identifies each site-wide characteristic set and maps it to a list of categories to exclude (SiteWideCharacteristicSets.ExcludeCategoryID). You can assume that any category that is not in the list of excluded categories supports the specified site-wide characteristic set.

Once you have retrieved the meta-data mappings, you generally use the information in one of the following ways (for any given listing):

If the seller is listing the standard way and the category supports Item Specifics, you would get the characteristic set ID from the mappings and use it as input to the GetAttributesCSCall request or a class that implements the IAttributesXmlProvider interface. (See Retrieving Item Specifics Meta-Data for information about executing GetAttributesCSCall.)
If the category is catalog-enabled and the seller chooses to list with Pre-filled Item Information, use the response to determine which of the product search meta-data calls the category supports.
If the ProductSearchPageAvailable flag is true, it means the category supports single-attribute product searches (i.e., searches based on meta-data from GetProductSearchPageCall).
If the ProductFinderID property contains an ID (or the ProductFinderAvailable flag is true), it means the category supports product finder-style searches, which are searches based on complex queries. (See Retrieving Product Finder Meta-Data for information about executing GetProductFinderCall). If the ProductFinderBuySide flag is true, the specified product finder is applicable for buy-side product finder searches (using GetSearchResultsCall). If it is false, the product finder is applicable for sell-side product finder searches (using GetProductSearchResultsCall).

Zero or more of the above options can be available for some categories. If you are not familiar with the basic differences between these product search options, see Summary of the Catalog Product Model.

If the category is a media category (Books, DVD & Movies, Music, or Video Games), you could use the mappings to make sure the category is catalog-enabled, and then give the seller the option to try to bypass the product search step and just specify an ISBN or UPC value in the listing details. (See Pre-filling a Listing Based on ISBN, EAN, or UPC Values (ExternalProductID) for information about executing AddItemCall with this type of information.)
All attribute-enabled categories also support searching for listings by using plain-text keywords. For this, you use GetProductSearchResultsCall and enter a query containing one or more words with optional wildcards.

The category-to-characteristic set mapping list for a given site is versioned. As the attribute meta-data contains a large volume of data, you can reduce the number of calls you make by retrieving and storing all the data once and then later retrieving only the information that changes. That is, before retrieving the entire list of mappings for a given site, check the mapping version. This is similar to the process you use to retrieve and store the eBay category hierarchy. See Maintain the Category-to-Characteristic Set Mappings.

This section describes the following process:

Prerequisites

Step 1:  Indicate the Category-to-Characteristic Set Data to Return

Step 2:  Make the API Call

Step 3:  Store the Response for Future Use

Step 4:  Maintain the Category-to-Characteristic Set Mappings

Step 5:  Note: Next Steps

Prerequisites

Before using GetCategory2CSCall, make sure your locally cached category data is up to date (see Categories.

Step 1: Indicate the Category-to-Characteristic Set Data to Return

As the GetCategory2CSCall response contains a large volume of data, you should retrieve and store all the data once and then retrieve only the information that changes. This is similar to the process you use to retrieve and store the eBay category hierarchy. If you are using the Attributes Library, the same principle applies when working with classes that implement ICategoryCSProvider, such as the CategoryCSDownloader class.

The first time you execute GetCategory2CSCall or your data-source provider class, you should retrieve all the available data.

After initially obtaining the mapping structure, in subsequent calls specify the locally saved version of the mapping in the AttributeSystemVersion filter to check whether the mapping version has changed. If it has, use the version information to get changes that have been made to the mappings. Use the GetCategory2CSVersion() method to retrieve only the version information.

You can expect the mapping information to be updated at least once or twice a month, but it may sometimes be updated more frequently than this interval. Use GetCategory2CSCall or your data-source provider class to check the mapping version at least once a day.

Optionally, use the CategoryID property as a filter to limit the results to a specific category. If not specified, then the mappings for all categories are returned. To determine the available category IDs, execute GetCategoriesCall or look up the IDs in the category hierarchy data that you have stored locally.

These properties are also described in GetCategory2CS.

When you use the Attributes Library to retrieve category-to-characteristic set mapping data, you create an instance of the AttributesMaster class and configure it to use a data-source provider, such as the CategoryCSDownloader class.

The example below shows how to do this:

Example 19-1 Setting up a Characteristic Set Mapping Data-Source Provider 

AttributesMaster amst = new AttributesMaster(); Session[Global.ATTRIBUTES_MASTER] = amst; ApiContext asn = (ApiContext)Session[Global.APISESSION]; // Set common site for all calls. asn.Site = (SiteCodeType)Session[Global.SITE]; CategoryCSDownloader ctd = new CategoryCSDownloader(); // Make the API call (see Make the API Call)

Step 2: Make the API Call

Making the API call with the Attributes Library entails invoking the CategoryCSDownloader.downloadCategoryCS( ) method, and then storing the returned mappings into an array of Category objects. If you create your own data-source provider class that implements the ICategoryCSProvider interface, your class would call the GetCategory2CS( ) method defined on the GetCategory2CSCall class to retrieve the data. Note: In the example below, the ctd variable holds the data-source provider, which is used to configure the AttributesMaster object (amst).

Example 19-2 Making the API Call 

// Download the category-to-characteristic set mappings ctd.DownloadCategoryCS(asn); // Configure the AttributesMaster object amst.CategoryCSProvider = ctd;    // Create a category collection that contains the downloaded data CategoryTypeCollection cats = ((CategoryCSDownloader)amst.CategoryCSProvider).CategoriesCS; CategoryTypeCollection catFull = Global.CallGetCategories(asn); foreach (CategoryType catF in catFull) {    CategoryType cat = Global.FindCategory(cats, catF.CategoryID);    if (cat != null)    {       cat.CategoryName = catF.CategoryName;       cat.LeafCategory = catF.LeafCategory;    } } Session[Global.CATEGORIES] = cats;} // Catch and handle errors, displaying appropriate messages for the end-user // See Error Handling for information about handling infrastructure errors

The returned data contains one or multiple (typically many) Category objects, one for each of the categories returned.

See GetCategory2CS Output Fields or the library reference documentation for a list of the kind of data that is returned.

An application needs to traverse the Category objects in the list of Category objects to visit each one and inspect its properties.

If a category supports Item Specifics, the category data includes a CharacteristicsSets property that contains the name of the characteristic set (in the Name property), an AttributeSetID property and other data. Depending on your application's workflow, you can use the characteristic set name to populate a list in your application's user interface, from which the user can select the attribute-enabled category in which to list a new item.

GetCategory2CSCall also returns the version of the complete list of mappings.

Some categories support site-wide characteristic sets for features like return policies. See Summary of the Attributes Model for information about site-wide characteristic sets.

Step 3: Store the Response for Future Use

Your application should store the category data with the mappings in some persistent manner (such as a database table) to have the data available whenever the application is run.

You can also use the mapping data in combination with the category hierarchy information retrieved from GetCategoriesCall to keep track of which categories are catalog-enabled. Note:

If you retrieved all mappings (with no CategoryID filter), store the version information so that you can use it as input the next time you execute the call.

Step 4: Maintain the Category-to-Characteristic Set Mappings

At the beginning of each day that you will use the mappings, retrieve any updates that have been made to the mappings. See GetCategory2CS Detail Controls.

Step 5: Note: Next Steps

Once you have retrieved the meta-data mappings, your next steps depend on whether the data has changed since the last time you retrieved it. If it has, you should update the rest of your locally stored meta-data as described in this chapter. See these topics:

For listing the standard way with Item Specifics:

Retrieving Item Specifics Meta-Data

Retrieving the Item Specifics SYI XSL Stylesheet

For listing with Pre-filled Item Information:

Retrieving the Item Specifics SYI XSL Stylesheet

Retrieving Product Search Page Meta-Data

Retrieving Product Finder Meta-Data

Retrieving the Product Finder XSL Stylesheet