eBay SDK for Java
Attributes & Catalogs > Searching for Pre-filled Item Information > Searching for Catalog Products 
 



< Back Next >

Searching for Catalog Products

In order to list an item based on a stock catalog product, you first need to find the stock product. We offer a number of ways to search for stock product content (see Calls You Use to List with Pre-filled Item Information).

This section describes how to search for catalog products by using GetProductSearchResultsCall.

Searching with a Single-Attribute Search Page

Searching with a Sell-Side Product Finder

Searching with Plain-Text Keywords

Configuring and Retrieving Product Search Results

Searching with a Single-Attribute Search Page

This section summarizes how to use GetProductSearchResultsCall when you want to perform a single-attribute search (based on search attributes retrieved from GetProductSearchPageCall).

To search for stock product information by using a product search page-based search:

  1. The seller selects a category for a listing.
  2. Your application determines that the category is catalog-enabled and supports single-attribute searches (see Retrieving Category-to-Meta-Data Mappings).
  3. Your application retrieves the product search page meta-data for the category from your local data store. This is the search page data you stored after executing GetProductSearchPageCall (see Retrieving Product Search Page Meta-Data).
  4. Your application presents the search attributes (ProductSearchPage.SearchCharacteristicsSet) property and data elements (ProductSearchPage.DataElements property) to the user.

    5. Each search and sort attribute includes a display sequence (Characteristic.DisplaySequence), which is the suggested order in which the attribute should be presented to the user (e.g., in a drop-down list). 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.

    The first sort attribute (i.e., the one with the lowest display sequence value) is also used as the default sort key to sort the products returned by GetProductSearchResultsCall, if you do not specify a sort attribute in the GetProductSearchResultsCall request.

  5. (Optional) The user chooses the sort order for the results. (Alternatively, just use the default sort order or specify an initial sort order without prompting the user.)
  6. The user selects the search criteria they want to use, such as Title, and enters a string to search on, such as "Harry Potter" (without the quotes).
  7. Based on the seller's selections, your application creates a ProductSearchType object.
  8. Your application executes GetProductSearchResultsCall, passing the ProductSearchType object in the ProductSearch property of the request. See Configuring and Retrieving Product Search Results.

Product Search Considerations when Listing in Two Categories

A listing can only include one set of Pre-filled Item Information. If the seller is listing an item in two categories, there are some rules that govern which category the product will be associated with.

Basically, if the primary category is catalog-enabled, the Pre-filled Item Information must be associated with that category. If the secondary category is catalog-enabled, the Pre-filled Item Information can be associated with that category only if the primary category is not also catalog-enabled.

More formally, use the following rules to determine which characteristic set to search in (and, therefore, which search meta-data to retrieve from your local data store):

Searching with a Sell-Side Product Finder

This section summarizes how to use GetProductSearchResultsCall when you want to search for products in an eBay catalog (a sell-side search) based on search attributes from GetProductFinderCall or a data-source provider that implements IProductFinderXmlProvider). Specifically, it focuses on using a product finder in the Sell Your Item use case. Note:

For information about using a product finder to search for listed items (a buy-side search), see Searching by Item Specifics (Buy-Side Product Finder).

To search for stock product information by using a product finder:

  1. The seller selects a category for a listing.
  2. Your application determines that the category is catalog-enabled and has a product finder available (see Retrieving Category-to-Meta-Data Mappings).
  3. Your application retrieves the product finder meta-data for the category from your local data store. This is the product finder data you stored after executing GetProductFinderCall or your data-source provider class (see Retrieving Product Finder Meta-Data).
  4. Your application presents the product finder to the user.

    5. If your application uses a graphical user interface, we recommend that you use the Product Finder XSL stylesheet to render the product finder. See Retrieving the Product Finder XSL Stylesheet and Working with the Product Finder XSL Stylesheet.

  5. The seller selects the search criteria they want to use, such as a particular Brand and Resolution.
  6. Based on the seller's selections, your application creates a ProductSearchType object.

    7. If you do not specify a sort attribute when you send the GetProductSearchResultsCall request, the first sort attribute is used as the default sort key to sort the products returned by GetProductSearchResultsCall. The first sort attribute is the sort attribute with the lowest display sequence value as returned from GetProductFinderCall or a data-source provider that implements IProductFinderXmlProvider) .

  7. Your application executes GetProductSearchResultsCall, passing the ProductSearchType object in the ProductSearch property of the request. See Searching for Catalog Products.

Searching with Plain-Text Keywords

You can search on a particular keyword that appears in a product's title or Item Specifics. For this, you use GetProductSearchResultsCall and and pass in one or more text strings (with optional wildcards) in the QueryKeywords property.

When you use a keyword query, the search criteria are not restricted to the results of a product search page or product finder, so the criteria are not tied to a particular characteristic set. This means you can search across multiple characteristic sets using the same query. This is useful when the user wants to broaden their search across multiple categories. For example, a seller who sells Jazz books, Jazz CDs, and Jazz movies may want to search for "Bird" across multiple categories. Specify the characteristic set IDs of interest in the CharacteristicSetIDs field of the ProductSearch object.

This section summarizes how to use GetProductSearchResultsCall when you want to perform a plain-text keyword search.

To search for stock product information by using simple keywords:

  1. The seller selects one or more categories in which to search. Alternatively, the seller can search across all categories.
  2. If specific categories are selected, your application determines that the categories are catalog- enabled and identifies the characteristic sets to which they are mapped (see Retrieving Category-to-Meta-Data Mappings).
  3. The seller specifies the search criteria they want to use by entering a search string. See Searching by Keywords for a list of applicable wildcards.
  4. Based on the seller's selections, your application creates a ProductSearchType object.
  5. Your application executes GetProductSearchResultsCall, passing the ProductSearchType object in the ProductSearch property of the request. See Searching for Catalog Products.

Configuring and Retrieving Product Search Results

Execute GetProductSearchResultsCall to return a list of catalog products that match a user's query. As catalog content can be quite large, you cannot store product information locally in order to perform searches against the data locally. You need to execute GetProductSearchResultsCall each time you want to perform a search.

This section describes the following process:

Prerequisites

Step 1:  Define the Basic Search Criteria

Step 2:  Limit the Quantity of Products Returned Per Family

Step 3:  Specify the Product Sort Criteria

Step 4:  Specify Pagination Properties

Step 5:  Make the API Call

Step 6:  Retrieve More Pages (If Necessary)

Step 8:  Next Steps

Prerequisites

Step 1: Define the Basic Search Criteria

To search for Pre-filled Item Information, you need to configure a query and pass it in the GetProductSearchResultsCall request.

To create a query, you create a ProductSearchType object and assign to it one or more search attributes with values that the user has selected, or specify a search string:

GetProductSearchPageCall and GetProductFinderCall return the list of attributes that can be used as search criteria (these vary per characteristic set).

For each search attribute in a product search page or product finder query, use the attribute's ValueList.ValueLiteral field(s) to specify the search strings to match. The catalog search engine is not case-sensitive, and it ignores articles (e.g., "the"), prepositions (e.g., "of"), and punctuation (e.g., ":") in the keyword string. It performs exact matches on alphanumeric strings (i.e., strings bounded by white space). This means it does not support regular expressions and other search patterns. However, you can use an asterisk (e.g., *) as a wildcard. For example, "s" would not return "My Favorite Movie: The Sequel", but "Favorite" or "Favorite Movie" or "sequel" or "seq*" would. This also means dates, ISBN values, and 12-digit Universal Product Code (UPC) values should be specified completely. The product search page and product finder meta-data for a given category often return data elements that contain useful instructions and links that your application can use to help users enter values correctly.

Note: The search engine may match on UPC values that are missing the first and/or last digit. However, eBay recommends that users specify the complete 12-digit value.

The ProductSearch property of the GetProductSearchResultsCall object takes an array of ProductSearchType objects. This lets you perform multiple queries (a batch query) in the same call. Batch queries may be useful for sellers who are listing several different items at the same time.

In each query, you also specify the characteristic set in which you are searching, plus other filters and pagination instructions (see additional steps below). If you are performing a product finder-style search, also specify the ID of the product finder you are using. For keyword queries, the characteristic set IDs are optional.

GetProductSearchResults describes the properties you can set when configuring a GetProductSearchResultsCall request. The input for GetProductFamilyMembersCall is nearly identical.

The example below shows one way to configure a product search query object for a single-attribute search.

In this example, the selCats array contains the category that the user selected. The search is being conducted in the DVDs & Movies characteristic set. The search attribute is the DVD title (attribute ID 183) with "Harry Potter Secrets" as the search string. The results should return approximately 50 products per page. In this case, the default maximum quantity of products per family will be used. The sort attribute is the film director (attribute ID 25080). 

Example 21-1 Configuring a Single-Attribute Product Search Query 
try 
{ 
   ProductSearchType pst = new ProductSearchType(); 
   pst.setAttributeSetID(selCats[0].getCharacteristicsSets(0) 
        .getAttributeSetID().intValue()); 
   SearchAttribute sa = new SearchAttribute(); 
   sa.setAttributeID(new Integer(183)); 
   Value val = new Value(); 
   val.setValueID(new Integer(ValueIds.TEXT)); 
   val.setValueLiteral("Harry Potter Secrets"); 
   sa.addValue(val); 
   pst.setSearchAttributes(new SearchAttributesType[] {sa}); 
   PaginationType pgn = new PaginationType(); 
   pgn.setEntriesPerPage(new Integer(50)); 
   pgn.setPageNumber(new Integer(0)); 
   pst.setPagination(pgn); 
   pst.setSortAttributeID(new Integer(25080));

In this example, the searchCat variable specifies the category the user selected. The query specifies a maximum of 50 products per page, with a maximum of 5 products per family. The search attributes are retrieved from a Map object that contains the data the user selected. The ProductFinderMaster class includes a number of useful methods that make it easier to work with the attributes the user selected. For example, the nameValuesToAttributeSets( ) method parses the attributes the user selected and converts the data to an array of SearchAttributeSet objects (if you rendered the product finder using the Product Finder XSL stylesheet). If you choose not to use the ProductFinderMaster class or if you create your own implementation of IProductFinderMaster interface, you would need to write additional code in order to work with the Product Finder XML and XSL stylesheet.

Example 21-2 Configuring a Product Finder Search Query  
ProductFinderMaster pfm = new ProductFinderMaster(); 
if( searchCat != null ) 
{ 
   try 
   { 
      // Extract data from HTML form post data. 
      SearchAttributeSet[] sets = pfm.nameValuesToAttributeSets( 
                                        request.getParameterMap()); 
      ProductSearchType[] pst = new ProductSearchType[sets.length]; 
      for(int i = 0; i < pst.length; i++ ) 
      { 
         SearchAttributeSet set = sets[i]; 
         ProductSearchType st = new ProductSearchType(); 
         pst[i] = st; 
         st.setProductFinderID(new Integer(set.getProductFinderID())); 
         st.setSearchAttributes(set.getSearchAttributes()); 
         st.setAttributeSetID(set.getAttributeSetID()); 
         st.setMaxChildrenPerFamily(new Integer(5)); 
         PaginationType pgn = new PaginationType(); 
         pgn.setEntriesPerPage(new Integer(50)); 
         pgn.setPageNumber(new Integer(0)); 
         st.setPagination(pgn); 
      }

Step 2: Limit the Quantity of Products Returned Per Family

This step describes how to use the MaxChildrenPerFamily input filter on the ProductSearch object. In order to understand how to use this filter, you first need to understand how the search results are organized in the response.

Sometimes several versions (or editions) of a product may be available. All versions of the same product are considered to be part of the same product family. Some product families may contain only one product; others may contain many products.

If a particular product has more than one version, the versions are grouped under a header row that summarizes some common attributes that all products in the same family share. In the figure below, three product families are returned. One contains three products (versions), one contains only one product, and one contains too many products to show on the current page. A product can also have a stock photo. On the eBay Web site, the stock photo appears adjacent to the product, and it also appears in the header row.

Figure 21-1 A List of Product Search Results on the eBay Web Site

Each product in the response contains a list of attributes. If the product family members are grouped under a header row, the header contains a subset of attributes that are common to all the products in the family. The combination of attributes in the header can vary for each characteristic set, and it is based on the attributes returned in the product header rows on the eBay Web site.

In the API, the header is modeled as a ProductFamilies.ParentProduct object, and each product is a ProductFamilies.FamilyMembers object.

As some queries may return many products, you may want to retrieve one product or a few representative products per family initially. This lets the user quickly discern whether a particular group of products matches the item to be listed. Use the MaxChildrenPerFamily input filter to limit the number of members returned per family. The default is to return no more than five (5) members per family. As this call supports batch searches, each ProductSearch object can specify a different value for MaxChildrenPerFamily.

On the eBay Web site, if a product family contains only one product, no header row is shown. However, in the GetProductSearchResultCall response, the ProductFamilies.ParentProduct header object is always returned for each ProductSearchResult.AttributeSet object in the response, even if only zero or one product is returned in the ProductFamilies.FamilyMembers object.

Conversely, if a product family is large, only the header is shown on the eBay Web site (with no products). In this case, the user can click a View Versions button to view all products in that family (see Figure 21-1). Similarly, in the GetProductSearchResultCall response, if the quantity of products in the family is greater than the value of MaxChildrenPerFamily, only the product family header (the ParentProduct node) is returned, and none of the family member products are returned. In this case, the ProductFamily.hasMoreChildren flag returns a value of true to indicate that there are products available. You can try calling GetProductSearchResults again with a higher value in MaxChildrenPerFamily, or you can execute GetProductFamilyMembersCall to return all products in the family in paginated form (see below and see Retrieving All Members of a Product Family).

If the actual quantity of products in the family is less than the value of MaxChildrenPerFamily, all product family members are returned. The ProductFamily.hasMoreChildren flag returns a value of false in this case.

For example, suppose you pass a value of 5 in MaxChildrenPerFamily in a query. In the corresponding response:

The maximum value you can pass in MaxChildrenPerFamily is 20000.

Step 3: Specify the Product Sort Criteria

If you want to specify the attribute by which the products will be sorted, use the SortAttributeID property of the query object. GetProductSearchPageCall and GetProductFinderCall retrieve the list of attributes that can be used as sort keys (these vary per characteristic set). If you do not specify a sort key, the default is the sort attribute that GetProductSearchPageCall or GetProductFinderCall returned with the lowest DisplaySequence value.

The sorting takes precedence over the product family groupings. This means products in the same family can be split into separate ProductFamily objects. For example, suppose you specify the title "My Favorite" as the search criterion, and you specify the Publication Year attribute as the sort key. The results would be sorted first by publication year, and related products with the same title would be grouped into a ProductFamily object. For example, several editions of "My Favorite Movie: The Sequel" released in 1999 might be returned in one ProductFamily object, and several editions of "My Favorite Movie: The Sequel" published in 2002 might be returned in another ProductFamily object. On the other hand, if the same query were sorted by title, all editions of "My Favorite Movie: The Sequel" might be returned in the same ProductFamily object.

Figure 21-2 shows a search response (on an eBay Web site) that returns six (6) products sorted by Title. Four of the products have the same title and are grouped under one product family header.

Figure 21-2 Product Search Results Sorted by Title

Figure 21-3 shows a search response that returns the same six (6) products sorted by publication year. Four products have the same title, but this time two of the products with the same title are grouped under one product family header (for the year 2000), and the other two with the same title are grouped under another header (for the year 1996).

Figure 21-3 Product Search Results Sorted by Publication Year

Step 4: Specify Pagination Properties

Like other calls that support pagination, GetProductSearchResultsCall lets you control how much data to return per page.

In a product search result, each product (in the ProductFamilies.FamilyMembers array) counts as an entry. Each header (ProductFamilies.ParentProduct) also contains a set of attributes that can be considered collectively as a single row of data. Thus, each ParentProduct node can also count as an entry, unless the family contains only one product (see Specifying the Entries Per Family and Per Page).

If the current search result does not represent the last page of results (relative to the sort order), the ProductSearchResult.HasMore flag returns a value of true.

The ProductSearchResults.ApproximatePages property roughly indicates how many more pages of matching results exist. For the initial query, assign a value of 0 (zero) to the PageNumber property (to retrieve the first page). If more pages exist, call GetProductSearchResults again and increment the PageNumber value to retrieve additional pages. See Retrieve More Pages (If Necessary) for a more detailed discussion of how to retrieve additional pages.

Specifying the Entries Per Family and Per Page

These are the rules for determining the entries per product family:

Typically, multiple product families are returned per page (depending on the size of the page, the MaxChildrenPerFamily value, and the actual quantity of products found). Use the Pagination.EntriesPerPage property to specify the approximate number of entries to retrieve per search response (i.e., per page). The actual number of entries that are returned could exceed the value by up to the value you specify in MaxChildrenPerFamily, depending on the size of the last product family returned for the page (i.e., EntriesPerPage should be considered an approximate value). If the last product family returned contains MaxChildrenPerFamily products or fewer, the extra family members are also returned to save you another call.

For example, suppose that EntriesPerPage is 50, a product family header is returned as line 49, and that product family contains eight (8) members:

The maximum value you can pass in Pagination.EntriesPerPage is 50000.

Step 5: Make the API Call

Making the API call entails declaring an array of ProductSearchResult objects (to hold the return data), invoking the getProductSearchResults( ) method on GetProductSearchResultsCall, and storing the getProductSearchResults( ) return value into the previously declared array of ProductSearchResult objects.

The example below shows retrieving product search results by using GetProductSearchResultsCall (the psrc variable). After the call is executed, the results are printed to standard output.

Example 21-3 Making the API Call  
   GetProductSearchResultsCall  psrc = new GetProductSearchResultsCall(apiContext); 
   // Make the call 
   ProductSearchResultType[] srs = psrc.getProductSearchResults( 
                                     new ProductSearchType[] {pst}); 
   // Handle case where no match is found 
   if( srs == null || srs.length == 0 || srs[0].getProductFamilies() == null ) 
      throw new SdkException("No matches returned for your query. Please try again."); 

   // Present the first search result 
   ProductSearchResultType psr = srs[0]; 
   ProductFamilyType[] families = psr.getProductFamilies(); 
   numberOfFamilies = eBayUtil.intToString(families.length); 
   totalProducts = eBayUtil.intToString(psr.getTotalProducts()); 
   System.out.println("Product Search Results: " + numberOfFamilies + " of "  
                                                 + totalProducts); 

   for(int i = 0; i < families.length; i++ ) 
   { 
      ProductFamilyType fm = families[i]; 
      ProductType[] prods = fm.getFamilyMembers(); 
      if( prods == null || prods.length == 0 ) 
         continue; 
      for(int n = 0; n < prods.length; n++ ) 
      { 
         ProductType prod = prods[n]; 

         // Print the stock photo URL, if any. 
         if( prod.getStockPhotoURL() == null ) 
         { 
            System.out.println("No stock photo available."); 
         } 
          else 
         { 
            String stockPhotoURL = prod.getStockPhotoURL().toString(); 
            System.out.println("Stock Photo: " + stockPhotoURL); 
         } 

         // Print the product title and details URL, if any. 
         String title = prod.getTitle() == null ? "No title" : prod.getTitle(); 
         System.out.println("Title: " + title); 
         String detailsURL = prod.getDetailsURL() == null ? "" : 
                             prod.getDetailsURL().toString(); 
         System.out.println("View Details " + detailsURL); 

         // Print the product attributes 
         CharacteristicType[] css = prod.getCharacteristicsSet().getCharacteristics(); 
         if( css != null ) 
         { 
            for(int k = 0; k < css.length; k++ ) 
            { 
               CharacteristicType ct = css[k]; 
               String lbl = ct.getLabel() != null ? ct.getLabel().getName() : ""; 
               System.out.println(lbl); 

               String val = ""; 
               if( ct.getValueList() != null && ct.getValueList().length > 0 ) 
               { 
                    ValType vt = ct.getValueList()[0]; 
                    val = vt.getValueLiteral(); 
                    if( val == null ) 
                       val = vt.getValueID().toString(); 
                    System.out.println(val); 
               } 
            } //for(k=0 
         } //if css 
      } // for(n..) loop 
   } //for(i..) loop 
} // try 
// Catch and handle errors, displaying appropriate messages for the end-user

If no match is found or too many matches are found for a particular query, a warning is returned and the TooManyMatchesFound flag returns a value of true. Separate errors are returned for each query passed in this batch call.

If you did not specify a sort attribute in the request, the products in the response are sorted according to the sort attribute with the lowest display sequence value (0). This is the DisplaySequence that was returned in the SearchPage.SortCharacteristics object of the GetProductSearchPageCall response. For example, when you search for a book, the default sort attribute is usually Title.

Within each product (ProductSearchResult.AttributeSet.ProductFamilies.FamilyMembers) object returned from GetProductSearchResultsCall, the order of the individual attributes is indicated in the CharacteristicsSet.Characteristics.DisplaySequence property. For example, for any given book, the Title attribute is shown first, followed by the Author attribute. The order of the individual attributes shown for a given product is not affected by the sort attribute you specify in the request. The sort attribute only affects the order in which the products (and product families) are sorted.

Each product is associated with detailed information, such as film credits or information from the publisher. On the eBay site, the user clicks a View Details link to view this supplemental information. You cannot retrieve this information directly through the API. Instead, each product object returns a URL (DetailsURL) for the eBay site page that contains the information.

Figure 21-4 Additional Details for a Product on the eBay Web Site

The response contains the results of a query, one for each query specified in the request.

See GetProductSearchResults for a summary of the fields that are returned by eBay.

Step 6: Retrieve More Pages (If Necessary)

If the current search response does not represent the last page of results (relative to the sort order), the ProductSearchResult.AttributeSet.HasMore flag returns a value of true.

Note: HasMore applies to the entire search response (all product families), whereas hasMoreChildren on a given product family object (i.e., ProductFamilies[n].hasMoreChildren) applies to a single product family.

The ProductSearchResult.AttributeSet.ApproximatePages property roughly indicates how many more pages of matching results exist. The value is calculated by dividing the total quantity of products found (ProductSearchResults.AttributeSet.TotalProducts) by the median quantity of products per page examined so far (given the entry count logic described above and assuming subsequent requests will specify the same EntriesPerPage and other filters). This optimization helps to shorten this batch call's response time.

For the initial query, you specified PageNumber = 0 (the first page). If more pages exist, call GetProductSearchResults again and increment the PageNumber value to retrieve additional pages. You can retrieve additional pages as a batch query in a single call or in separate calls. For example, suppose a query would return 200 entries and each product family happens to contain no more than 4 children. If you want to retrieve about 20 entries per page (with a EntriesPerPage of 20 and a MaxChildrenPerFamily of 4), you could:

The response does not return the current page number. Therefore, your application should keep track of the PageNumber value that was specified in the search request.

Note: If you specify a large value for MaxChildrenPerFamily (up to a maximum of 20000), and if a large product family spans multiple pages, the complete ProductFamily object (including the ProductParent object) is returned for each page. Only the list of products within the ProductFamily.FamilyMembers object varies.

Step 7: Identify Products That Have Been Used to List Items

Search results can include several very similar products. If you want to determine which products other sellers have used to pre-fill their listings, examine the Product.NumItems, Product.MinPrice, and Product.MaxPrice properties for non-zero values.

The number of items is the number of active (not ended) items that were pre-filled from the product. The minimum and maximum prices are the lowest and highest prices of active and ended listings that were pre-filled from the product. Note that because the value of NumItems only represents active listings, it may have a value of 0 even though the MinPrice and MaxPrice properties have positive values. If the seller is interested in analyzing prices in order to choose a start price or reserve price, it may also be useful to use GetItemRecommendationsCall to retrieve the average start prices and average sold prices of similar items that have been sold successfully.

To retrieve details about the listed items that have been pre-filled based on a product, use GetSearchResults and pass in the product's ID. See Searching by Product ID.

Step 8: Next Steps

Each product in the response has a product ID (ProductFamily.FamilyMembers.productID). Once the seller has selected a product, use that product's ID as input to GetProductSellingPagesCall to retrieve the product's Item Specifics and other information (see Retrieving a Product's Item Specifics).

The header is not a product, so it returns the ID of one of its product children as a representative product ID. If the product family is large and only the header is returned, you can pass this ID as input to GetProductFamilyMembersCall to retrieve all products in the family. See Retrieving All Members of a Product Family. The seller can then select a product, and you can use that product's ID as input to GetProductSellingPagesCall to retrieve the product's Item Specifics and other information (see Retrieving a Product's Item Specifics).


< Back Next >


 
Attributes & Catalogs > Searching for Pre-filled Item Information > Searching for Catalog Products 
© 2005–2007 eBay Inc. All rights reserved.