Retrieving Product Finder Meta-Data

The information in this section is applicable for applications that support listing with Pre-filled Item Information.

This section discusses the means and strategies for retrieving meta-data that you can configure to perform a product finder-style search against eBay catalog content.

A product finder is a tool that lets you specify search parameters that are only relevant to items within a particular category (or set of related categories). For example, a user may prefer to search for a book in a hardcover format only.

eBay supports two kinds of product finders:

Buy-side product finders search for listed items
Sell-side product finders search for catalog products that can be used to pre-fill listings (in the Sell Your Item flow)

Product finder searches are only supported in categories that have product finders available (see Retrieving Category-to-Meta-Data Mappings).

You determine the available product finder search criteria for a category (actually, for a characteristic set) by executing GetProductFinderCall. This call lets you specify product finder IDs to download a list of product finders, or retrieve all product finders for the target site. The Attributes Library includes an IProductFinderMaster interface and a sample ProductFinderMaster class that are designed to simplify the process of working with and rendering product finder meta-data. This master object uses a data-source provider that implements the IProductFinderXmlProvider interface. The Attributes Library also includes a sample data-source provider class called ProductFinderXmlDownloader, which executes GetProductFinderCall and caches the data in memory. If you want to use the Attributes Library, you can use this downloader class or you can create your own implementation of the IProductFinderXmlProvider interface that stores the data in a different way (such as in a database).

Each product finder specifies attributes that you can search on within the corresponding characteristic set, plus additional information. You use this information as input to GetProductSearchResultsCall for sell-side product finder searches and GetSearchResultsCall for buy-side product finder searches.

The product finder data for a given site is versioned. As the response can contain a large volume of data, you should retrieve and store all the data once and then retrieve only the information that changes. That is, before retrieving the entire list of product finders for a given site again, check the latest version. This is similar to the process you use to maintain category-to-characteristic set mappings (see Retrieving Category-to-Meta-Data Mappings).

This section describes the following process:

Prerequisites

Step 1:  Indicate the Product Finder Meta-Data to Return

Step 2:  Make the API Call

Step 3:  Store the Product Finder Data for Future Use

Step 4:  Maintain the Product Finder Meta-Data

Step 5:  Note: Next Steps

Prerequisites

Make sure your locally cached category-to-characteristics data is up to date (see Retrieving Category-to-Meta-Data Mappings).

Although you do not necessarily have to specify a product finder ID in order to execute GetProductSFinderCall (if you choose to retrieve all product finders at once), you will need to know whether a given category supports product finders before you can actually perform a product search during the Sell Your Item flow.

Step 1: Indicate the Product Finder Meta-Data to Return

As the product finder meta-data 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 category-to-characteristic set mappings. If you are using the Attributes Library, the same principle applies when working with classes that implement IProductFinderXmlProvider, such as the ProductFinderXmlDownloader class.

The first time you execute GetProductFinderCall or a class like the ProductFinderXmlDownloader class, you should retrieve all the available data.

After initially obtaining the meta-data, in subsequent calls use the locally saved version of the data in the AttributeSystemVersion filter to check whether the version has changed. If it has, use the version information to get the product finders that have changed.

Optionally, use the ProductFinderID property as a filter to limit the results to the product finder for a specific category. If you use a data-source provider class, you can pass these IDs as an array of int values when you retrieve the product finder meta-data. If no IDs are specified, the call returns product finder meta-data for all catalog-enabled categories that have finders available (i.e., where the the ProductFinderAvailable flag is set to true in the GetCategory2CSCall response). To determine the available product finder IDs, execute GetCategory2CSCall or use your data-source provider class to look up the IDs in the mapping data that you have stored locally.

See GetProductFinder for information on data filters like AttributeSystemVersion, ProductFinderID, and DetailLevel.

You can expect the meta-data to be updated at least once or twice a month, but it may sometimes be updated more frequently than this interval. Use GetProductFinderCall or use your corresponding data-source provider class to check the version once each day that your application is likely to search for catalog content, and then retrieve any changes to the meta-data if the version has changed.

These fields are also summarized in GetProductFinder Input Fields.

When you use the Attributes Library to retrieve product finders, you create an instance of the ProductFinderMaster class (or your own class that implements IProductFinderMaster) and configure it to use a data-source provider, such as the ProductFinderXmlDownloader class. The example below shows creating the master class and the data-source provider.

Example 19-9 Setting up a Characteristic Set Data-Source Provider 

try {    ProductFinderMaster        pfm = new ProductFinderMaster();    ProductFinderXmlDownloader axd = new ProductFinderXmlDownloader(apiContext);

Step 2: Make the API Call

Making the API call with the Attributes Library entails invoking the getProductFinderXml( ) method on your data-source provider class, which parses the returned XML string and creates an org.w3c.dom.Document object that is easier to work with. If you create your own data-source provider class that implements the IProductFinderXmlProvider interface, your class would call the getProductFinder( ) method defined on the GetProductFinderCall class to download the data and then use the getProductFinderData( ) method to retrieve the XML string locally without retrieving the same data from eBay again. In the example below, the axd variable holds the data-source provider. An array of product finder IDs (the pfIDs variable) is passed in the getProductFinderXml( ) method to retrieve the product finders. The data-source provider is then set on the ProductFinderMaster object (the pfm variable) to be retrieved later during the listing flow. At some point during your business workflow, you would also configure the product finder master object to use a category-to-characteristic set data-source provider so that you can render a product finder for a particular category. Depending on the design of your application, you might choose to do this as part of your meta-data management step or when you are ready to render a particular product finder for a particular category.

Example 19-10 Making the API Call 

axd.getProductFinderXml(pfIDs);    pfm.setXmlProvider(axd);    // Use AttributesMaster to configure the product finder master    // with the category-to-characteristic set provider    AttributesMaster        amst        = new AttributesMaster();    // Retrieve the meta-data mappings for categories    // See Retrieving Category-to-Meta-Data Mappings    ICategoryCSProvider csp = amst.getCategoryCSProvider();    pfm.setCategoryCSProvider(csp); } // Catch and handle errors, displaying appropriate messages for the end-user // See Error Handling for information about handling infrastructure errors

GetProductFinderCall returns a ProductFinderData string that specifies the XML for the product finder IDs that you specified in the request. Your data-source provider class should parse this string to create a Document object that will be easier to work with. See the ProductFinderXmlDownloader class for an example of how to do this.

See GetProductFinder and The Product Finder Meta-Data Model for information about the data fields that are returned.

See the generated library reference documentation for GetProductFinderCall and ProductFinderXmlDownloader for additional fields and methods that you can use to access and manipulate the retrieved data.

GetProductFinderCall also returns the version of the complete list of product finders (AttributeSystemVersion). The next time you execute this call, use the version information as a filter to retrieve only the data that has changed.

Step 3: Store the Product Finder Data for Future Use

Once you have retrieved the product finder meta-data, you can use the same meta-data for all product finder-style searches for the rest of the day. You should not need to retrieve the same data again for at least 24 hours.

Store the product finder data locally (e.g., to a database table).

Note: If you retrieved all the product finder data (with no ProductFinderID filters), store the version information so that you can use it as input the next time you execute the call.

Step 4: Maintain the Product Finder Meta-Data

You can expect the meta-data to be updated at least once or twice a month, but it may sometimes be updated more frequently than this interval. Use GetProductFinderCall to check the version once each day that your application is likely to search for catalog content, and then retrieve any changes to the meta-data if the version has changed.

Step 5: Note: Next Steps

When a user chooses to list or search in a category that supports a product finder search, transform the XML returned in the ProductFinderData field into HTML by using the Product Finder XSL stylesheet (see Retrieving the Product Finder XSL Stylesheet and Working with the Product Finder XSL Stylesheet). This helps you render a product finder in your application's user interface, from which the user can select the attributes and values to search on.

Once the user selects the attributes to search on and submits the page, the JavaScript that is included in the stylesheet will generate post data that you can use to determine the attributes and values that the user has selected.

For sell-side product finder searches, use the search attributes to configure a ProductSearch object and pass it to GetProductSearchResultsCall to perform the actual search. See Searching for Catalog Products.

For buy-side product finder searches, use the search attributes and configure a SearchRequest object and pass it to GetSearchResultsCall to perform the actual search. See Searching by Item Specifics (Buy-Side Product Finder).