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.

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.

The first time you execute GetProductFinderCall, 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 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 look up the IDs in the mapping data that you have stored locally.

See GetProductFinder for information on data filters like AttributeVersion, 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.

Step 2: Make the API Call

Making the API call entails calling the GetProductFinder( ) method defined on the GetProductFinderCall class to download the data and then use the GetProductFinderData property to retrieve the XML string locally without retrieving the same data from eBay again.

GetProductFinderCall returns a ProductFinderData string that specifies the XML for the product finder IDs that you specified in the request.

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 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 ProductSearchList 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).