Retrieving Product Search Page Meta-Data
The information in this section is only 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 single-attribute search against eBay catalog content. This section only describes how to retrieve the search page meta-data. For information about how to use the meta-data in a search, see Searching for Pre-filled Item Information.
On the eBay site, when the user selects a catalog-enabled category, the user is given the option to list with Pre-filled Item Information or to list the standard way. In case the user wants to list the item with Pre-filled Item Information, a list of search attributes is also presented.
You determine the available search attributes for a category (actually, for a characteristic set) by using GetProductSearchPageCall or GetProductFinderCall, depending on the search criteria the seller is using. (For information about GetProductFinderCall and the corresponding data-source provider defined in the Attributes Library, see Retrieving Product Finder Meta-Data.) Note:
GetProductSearchPageCall downloads a list of "search pages"—one for each characteristic set that you specify in the request. You can also retrieve all search pages for the site (i.e., for all catalog-enabled categories that support single-attribute searches). Each search page specifies search attributes and sort keys for catalog-enabled categories. You can use the data returned from GetProductSearchPageCall to present similar information to the user. The call also returns data elements (DataElement) that provide hints that may be helpful to users, such as how to enter an ISBN number.
When the user selects a catalog-enabled category (see Retrieving Category-to-Meta-Data Mappings) and the category has a search page available, present the corresponding search attributes to the user. The user can then select the search criteria (e.g., Title) and enter a value to search on. You use the selected attribute and value as input to GetProductSearchResultsCall.
The product search page 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 search pages for a given site again, check the mapping version. This is similar to the process you use to retrieve and store the eBay category hierarchy. See Maintain the Product Search Page Meta-Data.
This section describes the following process:
Step 1: Indicate the Search Page Data to Return
Step 2: Note: Make the API Call
Step 3: Store the Product Search Page Meta-Data for Future Use
Step 4: Maintain the Product Search Page Meta-Data
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 characteristic set in order to execute GetProductSearchPageCall, you will need to know whether a given category supports product search pages before you can actually perform a search during the Sell Your Item flow.
Step 1: Indicate the Search Page Data to Return
As the search page 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 GetProductSearchPageCall, 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 search pages that have changed.
Optionally, use the AttributeSetID property as a filter to limit the results to the search pages for a specific characteristic set. If not specified, then the call returns meta-data for all catalog-enabled categories that have product search pages available (i.e., where the ProductSearchPageAvailable flag is set to true in the GetCategory2CSCall response). To determine the available characteristic set IDs, execute GetCategory2CSCall or look up the IDs in the mapping data that you have stored locally.
See GetProductSearchPage for information on data filters like AttributeVersion, AttributeSetIDList, 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 GetProductSearchPageCall 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 properties are also summarized in GetProductSearchPageCall Input Fields.
The example below shows one way to configure a GetProductSearchPageCall object to search for product search pages. In this case, we are retrieving one search page for a particular category (indicated by the cat variable). Note:
try { // Make sure a product search page is available for the category Boolean spAvail = cat.getProductSearchPageAvailable(); if( spAvail != null && spAvail.booleanValue() ) { GetProductSearchPageCall psp = new GetProductSearchPageCall(apiContext); psp.setDetailLevel(new DetailLevelCodeType[] {DetailLevelCodeType.ReturnAll}); psp.setAttributeSetID(new int[] { cat.getCharacteristicsSets(0).getAttributeSetID().intValue()}); // Make the API call (see Make the API Call) } // If no search page is available, check to see whether a product finder is available. // See Retrieving Product Finder Meta-Data |
Step 2: Make the API Call
Making the API call entails declaring an array of ProductSearchPage objects (to hold the return data), invoking the getProductSearchPage( ) method on GetProductSearchPageCall, and storing the getProductSearchPage( ) return value into the previously declared array of ProductSearchPage objects. The example below shows retrieving product search page meta-data by using GetProductSearchPageCall (the psp variable).
ProductSearchPageType[] searchPages = psp.getProductSearchPage(); } // Catch and handle errors, displaying appropriate messages for the end-user // See Error Handling for information about handling infrastructure errors |
GetProductSearchPageCall returns a list of ProductSearchPage objects, each containing a list of search attributes, sort attributes, and other meta-data.Once the data has been cached in memory, you can use the getReturnedProductSearchPages( ) method to access the data without downloading it from eBay again.
GetProductSearchPageCall returns a list of ProductSearchPage objects, each containing a list of search attributes, sort attributes, and other meta-data. Once the data has been cached in memory, you can use the ProductSearchPageList property to access the data without downloading it from eBay againSee GetProductSearchPage for information about the properties that are returned by eBay.
As indicated above, this call is applicable only for characteristic sets that are mapped to catalog-enabled categories for which the ProductSearchPageAvailable flag is true. If you pass in one or more IDs for catalog-enabled characteristic sets, the call succeeds and the search criteria and sort keys are returned for the valid characteristic sets. If some characteristic sets are invalid, the normal data result set is accompanied by a list of errors. If all characteristic sets you pass in do not have product search pages available, the call fails.
The list of available sort attributes has no dependencies on the list of search attributes, though the data may intersect. For example, a product's Title attribute might be returned in a characteristic set's search attributes list and sort attributes list, but the product's release date or the manufacturer's suggested retail price (MSRP) might only be returned as sort attributes (i.e., they would not be valid search keywords).
Each search and sort attribute includes a display sequence (DisplaySequence), which is the suggested order in which they should be presented to the user in a list. The sort attribute with the lowest display sequence value (0) in the GetProductSearchPageCall response is used as the default sort attribute for GetProductSearchResultsCall if you do not specify a sort attribute in the GetProductSearchResultsCall request. Aside from that, use of the display sequence information is optional. That is, your application is not required to present sort keys to users in the same order as eBay does. Similarly, you can present the search attributes in any order.
GetProductSearchPageCall also returns the version of the complete list of search pages. Use the getReturnedAttributeSystemVersion( ) method to get this value from the cached response.
Step 3: Store the Product Search Page Meta-Data for Future Use
Once you have retrieved the GetProductSearchPageCall response, you can use the same meta-data for all searches for the rest of the day. You should not need to execute the call again for at least 24 hours.
Store the search page data object locally (e.g., to a database table).
If you retrieved all the search page data (with no AttributeSetID 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 Search Page Meta-Data
At the beginning of each day that the user will create or submit listings with Pre-filled Item Information, retrieve any updates that have been made to the search page meta-data.
Step 5: Note: Next Steps
When a user selects a catalog-enabled category and chooses to perform a single-attribute search, present that category's search page data to the user. Once the user has specified an attribute and value, use the attribute to configure a ProductSearch object and pass it to GetProductSearchResultsCall to perform the actual search. See Searching with a Single-Attribute Search Page.