Guide: Searching for Items by Using a Query

An application can enable users to search for items based on user-specified keywords and filter criteria. This is done on eBay using GetSearchResults.

Like all calls, GetSearchResults returns time values in GMT. See Time Values for information about converting between time zones.

In addition to searching for items, GetSearchResults can query for categories that contain matching items. See Searching for Matching Categories.

GetSearchResults supports filters that you can use to refine these queries. See Refining a Search by Using Filters and the topic for information about these filters. For information about controlling the data returned, including ways to control which fields are returned and the order of the returned items, see Controlling the Way Data Is Returned.

If a low number of items is returned, expanded results are returned (see Expanding a Search).

If the request specifies a value in the MaxRelatedSearchKeywords field, then related keywords can be returned in the response. Specifically, if there are keywords related to the original keywords, the response includes RelatedSearchKeywordArrayType, a container for recommended keywords.

Once the user has specified a search method, GetSearchResults then searches for item listings according to the search parameters. GetSearchResults also incorporates filter criteria properties that apply a cumulatively stricter filtering of the items found with the basic search. GetSearchResults returns an array of items that match the basic search and additional filtering criteria.

Searching by Keywords

Note: As of May 2008, the response for search related calls will not return an item with a listed price less than the Minimum Listing Amount (MLA) threshold on the eBay site where the item was originally listed. For more information, see Listing an Item.

GetSearchResults uses as the basis for returning items a search string specified in the required Query property of the GetSearchResults object. GetSearchResults searches for item listings where the keywords are found in the title and subtitle, returning those items in the result set. The value specified for Query can contain one or more keywords and combinations of wildcard characters. The words "and" and "or" are treated like any other word. Only use "and," "or," or "the" if you are searching for listings containing these words. You can use AND or OR logic by including certain modifiers. Wildcard characters (e.g., "*") are also supported. Be careful when using spaces before or after modifiers and wildcard characters (+, -, or *).

The following table shows the operators and character punctuation that can be used in GetSearchResults keyword queries, and what the effects of each are.

Table 26-1 Keyword Query Operators and Punctuation
Modifier	Purpose	Example	Returns
Space between words	Applies AND logic to multiple keywords.	baseball card	Items with both the words "baseball" and "card".
Comma between words, no parentheses	Applies AND logic to multiple keywords.	baseball,card	Items with both the words "baseball" and "card".
Comma between words in parentheses	Applies OR logic to multiple keywords.	(baseball,card)	Items with either the word "baseball" or the word "card".
Quoted words	Requires an exact sequence of words.	"baseball card"	Items with the exact phrase "baseball card".
-word	Specified word cannot be present.	baseball -autograph	Items that have the word "baseball" but not "autograph"
-(word, word, word)	Specified words cannot be present.	baseball -(autograph,card,star)	Items with the word "baseball" but not "autograph," "card," or "star".
*	Substitutes for one or more characters.	baseball*	Items starting with the string "baseball". Use "" by itself or with a minimum of 2 characters. Do not use "" by itself unless you are using CategoryID or you are searching by seller.
@ sign	Search must find two of three words from a list.	@1 baseball autograph card	Items with two of the three words "baseball," "autograph," and "card". For a "3 out of 4" search, use @2 and a list of four words.
+	Concatenates a query string using AND logic with another keyword.	@1 baseball autograph card +star	Items with any two of the three words "baseball," "autograph," or "card" in the title plus the word "star".

The following rules apply when there are spaces embedded in multi-word query strings:

In addition to the keywords in Query, GetSearchResults provides additional criteria for restricting and refining the search. These input properties of the GetSearchResults object act as a filter on the item listings that would be returned by the search using just the specified keywords.

GetSearchResults retrieves a list of the item listings that match the search criteria specified as input. This list is returned in the SearchResultItemArray property of the GetSearchResults response object. SearchResultItemArray is of type SearchResultItemArrayType, containing one SearchResultItemType object for each returned item listing matching the search criteria and surviving any additional filtering.

SearchResultItem has three properties: Item, ItemSpecific, and SearchResultValues. The Item property (type ItemType) contains the item data for the listing, including a property, BuyItNowPrice, that implies that the item includes the Buy It Now option. The ItemSpecific property (type NameValueListArrayType) contains the Item Specifics (attributes) for the listing. The SearchResultValues property contains additional information for the listing that is not normally returned in an ItemType object, such as whether there is a picture for the listing. The values that can appear in SearchResultValues are listed in the SearchResultValuesCodeType code list. These values are not mutually exclusive and more than one may be present for a given item listing (for example, the values Escrow and New).

Searching by Category ID

When you use a free-text query (in Query), you can restrict the search to a single category by passing the category ID in CategoryID. In this case, Query and CategoryID are processed using "AND" logic. You can use DetailLevel.ItemReturnCategories in a GetSearchResults request. If you do so, the results include the primary category of retrieved items and, if applicable, the secondary category.

To find all items in a leaf category, pass CategoryID and use an asterisk (*) in Query. This approach only works in leaf categories, not in meta-categories like 267 (Books).

With product finder searches (using SearchRequest), the product finder arguments take precedence over CategoryID if they are inconsistent.

For information about the distribution of items across categories that match the query, use the Categories arguments instead. See Searching for Matching Categories.

Searching by Item Specifics (Buy-Side Product Finder)

Sometimes it is useful to be able to specify additional filters 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. Instead of defining categories like Books : Fiction Books : Hardcover, eBay uses Item Specifics to specify very standard, category-specific item details like Format=Hardcover. (That is, Format=Hardcover is a very obvious piece of standard information that applies to book items, but it wouldn't make any sense for golf club items.)

On eBay, a search that queries Item Specifics is also called a product finder.

Figure 26-1 shows an example of the Fiction Books finder on the eBay US site. (To see this product finder yourself, go to the eBay Web site, search for a book, and then select "Fiction Books" in the Matching Categories list on the left side of the page.)

In the Fiction Books Finder, the attributes have book-specific names like "Category" and "Format". Each attribute has a list of possible values you can choose from, like "Science Fiction" and "Hardcover". eBay happens to show the values as links, you need to drill down into progressively finer Fiction Books finders to perform more detailed queries.

Figure 26-2 shows an example of the Tickets Finder on the eBay US site. In this product finder, the attributes have ticket-specific names like "Event Type" and "Number of Tickets", and the values have relevant names like "Sporting Events". In this case, eBay shows the values in drop-down lists, and you can configure all the options at once (without drilling down).

In the API, Item Specifics are implemented by using constructs called attributes (not to be confused with XML attributes).

When you use a product finder search, eBay only returns items that were listed with Item Specifics in the first place. These could be Item Specifics that the seller specified, or Item Specifics that were pre-filled from an eBay catalog.

When you use a product finder search, information about available buying guides may also be returned. See Searching for Reviews & Guides for additional information.

eBay's product finder search functionality is more complex to use than other search parameters, because you need to look up various IDs and programmatically handle certain dependencies (such as the relationship between a ticket's venue, city, and state). Therefore, for certain categories, we provide some alternative ways to search:

If you are searching for tickets, consider using TicketFinder instead of the full product finder functionality. This is a simplified product finder just for tickets, and it doesn't require you to learn about the details of attributes. See Performing a Simple Ticket Finder Search.

If you are searching for a particular product (such as a particular camera model) but you don't need the structured precision of a product finder, consider whether GetProducts might meet your needs. See Searching for Listings by ProductID.

If you are searching for items in only new or only used condition, use the ItemCondition field. This field works for sites that support a site-wide item condition, such as eBay Germany. (This field does not work for the eBay US site.) See Searching by Item Condition.

Performing a Simple Ticket Finder Search

As an alternative to the full product finder functionality, the API provides a simplified ticket finder for the eBay US, Germany, and UK sites. (Other sites don't support ticket finders in general.) To use this, specify TicketFinder in GetSearchResults. It supports these fields:

EventType—We define a particular set of event types for each site, such as US_Concerts. See the GetSearchResults documentation for a complete list.

EventDate—Search by various combinations of year, month, and day. See the GetSearchResults documentation for details.

StateOrProvince—Specify any state in the US.

CityName—Pass in the name of the city in which you want to find events.

TicketQuantity—The ticket finder recognizes certain common ticket quantities for each eBay site. See the GetSearchResults documentation for details.

As a general rule, the more of these fields you specify, the fewer results we'll return. (That is, we use AND logic for this search.) However, if we don't recognize a value (such as the city you requested), we'll drop that value and perform the search based on the other fields.

To search for tickets in a particular venue, you can usually get good results if you specify the venue name in Query and set SearchFlags to SearchInDescription. (which will also search for words in the Item Specifics, in many cases).

The ticket finder doesn't support searching for Event Subtype (e.g., Classical). If you need that level of precision, you can try specifying the subtype in Query (and set SearchFlags to SearchInDescription) to see if you get satisfactory results for your use case. Otherwise, you will need to use the full product finder. See Performing a Product Finder Search.

Also, when you search for tickets, you can optionally specify DetailLevel with a value of ItemReturnAttributes or ReturnAll to also see the venue, section, and row in the item results. This information is returned in the attributes format, so you need to use additional calls to map the numeric IDs to their human-readable labels. See Viewing Ticket and Vehicle Item Specifics in Search Results.

Performing a Product Finder Search

Here are the basic steps for configuring a product finder search. You will need to read other sections of this documentation to understand the details:

Use GetProductFinder to retrieve a list of the available product finders and their IDs. To be applicable for GetSearchResults, the product finder you choose must be identified as a "buy- side" product finder.

See GetProductFinder Sample for a sample. See The Product Finder Meta-Data Model for details about interpreting elements in the GetProductFinder response.

(Optional) If you plan to search against particular attributes and values, such as Format=Hardcover, drill down further into the product finder's child elements to find definitions of the attributes and values you want, and to find their corresponding IDs. (You need the IDs to use as input to GetSearchResults.)

If your application has a graphical user interface, you can use GetProductFinderXSL to retrieve an XSL stylesheet that you can use to render a product finder widget like the one shown in Figure 26-1.

Once you have selected a product finder, pass its ID in the SearchRequest.ProductFinderID field of GetSearchResults. See Search for Ticket Listings and Display the Venue, Section, and Row for a sample.

(Optional) If you are also searching against particular attributes, pass the attribute and value IDs in SearchRequest.SearchAttributes. (In some product finders, you can specify free-text values for certain attributes. See The Product Finder Meta-Data Model for details.)

When you are testing this functionality, first use a product finder in the Web site UI (to make sure you can configure a product finder query that returns items). Then use GetSearchResults in the Production environment and configure the request in a similar way. Start by specifying the product finder ID without any attributes. Once that works, try adding attributes so that you can understand the effects. GetSearchResults uses AND logic for most input fields. So, it's a good idea to avoid specifying other filters while you are testing a product finder search.

For additional tips and workarounds, search the Knowledge Base for "product finder". For example, these articles may be helpful for troubleshooting:

Viewing Ticket and Vehicle Item Specifics in Search Results

Note: At this time, you can't use the API to reliably determine which buy-side product finders are associated with each eBay category. Instead, show your users a list of available product finders, and they can choose the one they want to use.

When you use a product finder search, GetSearchResults sometimes returns a few Item Specifics in the results. However, this is not a full set of Item Specifics. GetSearchResults can only return the Item Specifics that would appear in product finder search results on the eBay Web site. Currently, this is only supported for event tickets and US eBay Motors vehicles.

For example, in the Tickets Finder results on the US site, the search results list page shows the Venue attribute below the listing title, and the Section and Row attributes in columns. But it doesn't show other attributes that have been set on the item, such as the Event Type and Number of Tickets attributes. The rest of the attributes are only shown on the View Item page for each listing.

Figure 26-3 shows one line from a set of Tickets Finder results. In this result, the venue is Qwest Field (as shown below the item title and above the subtitle), and the tickets are in section 310, row Z (as shown in the Section and Row columns).

GetSearchResults returns ticket attributes in the AttributeSetArray node.

If you use the Cars & Trucks Finder on eBay Motors US, the Mileage and Year attributes are returned in the ItemSpecifics node.

Most other product finders, such as the Fiction Books finder, don't return any Item Specifics in search results at all. To retrieve all of a listing's Item Specifics, use GetItem instead.

Also, GetSearchResults only returns vehicle Item Specifics for vehicles when you specify a product finder ID in the request (and you specify a detail level of ItemReturnAttributes or ReturnAll). This is because the eBay search engine needs to know the product finder ID in order to look up the attribute data. Similarly, it only returns ticket Item Specifics when you either specify a product finder ID or TicketFinder in the request (and the appropriate detail level).

Item condition attributes (if any) can be retrieved by passing IncludeCondition in the request. Also see Searching by Item Condition.

To test your application's ability to display Item Specifics in search results, first use the Ticket Finder (or the Cars & Trucks finder) to find items via the eBay Web site UI. This will help you configure a query that should work. Make sure you can see the Item Specifics in the search results list. Then use GetSearchResults and configure a similar product finder search in the Production environment. If you use the Cars & Trucks finder, start by specifying the product finder ID without any attributes. See Search for Ticket Listings and Display the Venue, Section, and Row for a sample.

Searching by Product

Note: A product is really anything that can be sold. However, to distinguish the eBay definition of a product vs. a listing or an item, we use the term product to mean stock information in a catalog.

For example, Figure 26-4 shows a product from the Books catalog. (This is not an item that can be purchased. It is a stock description of a book.)

A seller can take this product data and use it to pre-fill some of the details in their listings. (We call this product details or Pre-filled Item Information). Figure 26-5 shows some book listings that used this product data. In this case, the product is shown at the top, followed by listings that contain data matching the product.

eBay members can review products to help other members make buying decisions. These reviews aren't specific to any particular seller's items. (That is, a review of a book will describe the qualities of the book in general as a product, not the qualities of the actual object that someone is selling.) Figure 26-6 shows a product followed by a few reviews that members have written.

You can use the API to search for items based on this product data, or you can search for the products themselves and some of their reviews.

Searching for Products, Reviews, and Guides

In addition to searching for listings, you can also search eBay's product catalog for products.

Product searches can be useful to applications that support shopping comparison, product reviews, or basic supply and demand data.

To search for products, use GetProducts (see GetProducts). One common case is to start by specifying a keyword query. This retrieves a list of products with no listings, reviews, or guides. This is analogous (although not identical) to using this page on the eBay Web site:

With GetProducts, you can retrieve up to 2000 products that match a query. Each product includes basic details, such as the product title and Item Specifics. (Item Specifics are standardized details that are specific to the category. For example, a book's Item Specifics are fields like author, format, publication year, and ISBN. A ticket's Item Specifics are fields like Venue, Event Type, and Number of Tickets.)

Note: Some product content is provided to eBay by third-party providers. This means the API cannot return certain information, such as the detailed description text that is owned by the provider. Instead, we provide a link to the product detail page hosted on eBay.

For each product, you can retrieve additional information that would be useful to buyers, including top reviews by eBay members, buying guides (shopping advice), and up to 200 matching items. This information is similar to the information in the eBay Web site pages shown above in Searching by Product.

GetProducts also supports affiliate tracking for members of the eBay Affiliates Program. See Affiliate Tracking Concepts. eBay Affiliates earn commissions for driving traffic to eBay.

Searching for Listings by ISBN, UPC, or EAN

In media categories (Books, Music, DVDs & Movies, and Video Games) only, you can use an ISBN or UPC value instead of an eBay product ID to find listings that include catalog product details. Pass the ISBN or UPC value in the ExternalProductID property.

ExternalProductID essentially pre-fills the category, keywords, and Item Specifics in which to search. Therefore, you cannot pass in a value for Query, CategoryID, or ProductID when you use ExternalProductID.

Searching for Listings by ProductID

One way to search for listings with product details is to pass in the ID of the product you are looking for. If you do not know the product ID, use GetProducts to retrieve a list of catalog products. Obtain the product ID from one of these products and use it as input to GetSearchResults to find all items that were listed based on that product. See Searching for Products, Reviews, and Guides and see GetProducts Samples.

When you use ProductID in GetSearchResults, it essentially pre-fills the category, keywords, and Item Specifics in which to search. Therefore, you cannot pass in a value for Query, CategoryID, or ExternalProductID when you use ProductID.

Expanding a Search

If you specify that the ExpandSearch property of GetSearchResults is true, then search results are expanded when a small result set would otherwise be returned. For example, on the US site (SiteId 0), if a search would normally result in fewer than 10 items, the search results are expanded.

Specifically, the search returns items (if there are matches) in one or more of the following containers: InternationalExpansionArray (for items available from international sellers), FilterRemovedExpansionArray (for items that would be returned if filters such as PriceRangeFilter are removed), StoreExpansionArray (for items listed in the Store Inventory Format), and AllCategoriesExpansionArray (for items available if category filters are removed). The maximum number of items returned in each container is 6 to 10.

Searching for Matching Categories

Set the Categories properties in combination with Query, ExternalProductID, ProductID, or CategoryID to retrieve statistics about the distribution of matching items across the categories in which they are listed (e.g., to create a histogram). These categories are referred to as matching categories in this context.

In the response, sibling categories (i.e., categories at the same level in the hierarchy with the same parent category) are sorted (ranked) according to the number of items they contain that match the query. To control the maximum number of matching categories returned for each level in the hierarchy, use the Categories.MaxCategories and Categories.MaxSubcategories input properties. This is useful for applications that only display top hits.

Use each subcategory's parent ID to map the subcategory to its parent category. This is useful when multiple higher-level categories are returned and you want to present the results in a hierarchical format. A level 3 category will specify a level 2 category as its parent. The level 2 category will specify a level 1 category as its parent.

To retrieve category data for only the meta-categories (e.g., "Coins") without the statistics for lower-level subcategories (e.g., "Coins : World : Africa : Egypt"), or to only drill down to a certain level in the hierarchy, use the Categories.Levels input property.

For example, if you specify MaxCategories = 1, MaxSubcategories = 0, and Levels = 0, GetSearchResults only returns one first-level category (the one with the most items that match the request), such as the "Coins" meta-category.

If you specify MaxCategories = 1, MaxSubcategories = 1, and Levels = 4, GetSearchResults returns the following data:

If you specify MaxCategories = 4, MaxSubcategories = 2, and Levels = 3, GetSearchResults returns the following data:

Items can be listed in more than one category. Also, the number of items in a parent category includes the total number of items in its subcategories. This means the total count of all CategoryArray.Category.NumOfItems values in the response can exceed the total number of items that match the query (PaginationResult.TotalNumberOfEntries).

When you use a matching categories search that also retrieves item data, information about available buying guides may also be returned. See Searching for Reviews & Guides for additional information.

Searching for Reviews & Guides

Buying Guides are available in the Production Environment only. They are not available in the Sandbox.

When user searches for items in certain categories, the results may also include URLs for relevant buying guides.

Buying guides contain content about particular product areas, categories, or subjects to help buyers decide which type of item to purchase based on their particular interests. These guides are intended for buyers who do not already have a specific product in mind. For example, a digital camera buying guide could help a buyer determine what kind of digital camera is right for them.

For a list of buying guides that are currently available on the US site, see the Buying Guide hub:

Search queries may return URLs for multiple buying guides. Buying guides may be returned for a matching item's category as well as its parent and child categories. Information about each buying guide is returned in the same order that it would be displayed on the Web site. The guide for the current category (if any) is returned first. Then guides for its child categories are returned. Finally, guides for its parent categories are returned. When many buying guides are found, only URLs for the first few buying guides are returned. Use the URLs along with the buying guide names (also returned) to create links in your application to the buying guides.

Use GetProducts to find a product, and then retrieve the product's reviews and guides (see Searching for Products, Reviews, and Guides). GetProducts retrieves more buying guide details than GetSearchResults, and it also retrieves reviews.

Use GetSearchResults and perform matching categories search (see Searching for Matching Categories). GetSearchResults returns basic buying guide data (but no reviews) in BuyingGuideDetails.

Use GetSearchResults, and perform a product finder search (see Searching by Item Specifics (Buy-Side Product Finder)). GetSearchResults returns basic buying guide data (but no reviews) in BuyingGuideDetails.

Buying guide details are not necessarily returned for all searches, as some categories and product finders are not associated with buying guides. Also, when you specify TotalOnly or Categories.CategoriesOnly in your search request, buying guide details are not returned.

If you specify the CategoryID filter to search within a particular category, applicable buying guide details (if any) will be returned even if no listings match the query. If you do not specify the Category filter, applicable buying guide details (if any) will only be returned when listings that match the query are returned.

To test your application's ability to correctly present functional buying guide links, you can begin by testing against the US site. For example, you can search in these categories on the US site (use GetCategories to retrieve the latest category IDs):

Refining a Search by Using Filters

When performing searches with GetSearchResults or GetCategoryListings, use filters to help to refine the search. The filtering effect is cumulative unless otherwise specified. That is, Boolean AND logic is used in cases of multiple filters.

For example, if you set ItemTypeFilter to FixedPricedItem (for fixed price), the results will only search for fixed-price items (no auctions) that match the basic query (see Searching By Listing Type).

Unless otherwise specified in the reference documentation for GetSearchResults or GetCategoryListings, or in the reference documentation for a filter, you can use any filter in combination with search methods summarized in Searching for Items by Using a Query.

Using Search Flags

Use the SearchFlags to specify one or more criteria that affect which items are returned. SearchFlags is of type SearchFlagsCodeType. See that code list for all possible values and the definitions of each. Use a value of Charity to limit the items returned to just those that are charity listings (see Identifying Listings that Benefit Nonprofits for more on these items). Use a value of SearchInDescription to have the search look for the specified keywords in the description property of listings, not just the title and subtitle. Use a value of PayPalBuyerPaymentOption to limit the items returned to just those where PayPal is one of the payment methods offered by the seller. These values are not mutually exclusive and may be used together in the same call in various combinations. Specifying more than one criteria value in SearchFlags results in increasingly restrictive filtering.

Searching by Item Condition

Use the ItemCondition filter to search for new or used items. This field only has an effect for sites and categories that support a site-wide item condition, such as eBay Germany. See Site-Wide Item Condition Details. This field has no effect for the US site.

When you search by condition, we suggest you try combinations of these fields to see which combination gives you the results you need for your use case.

Specify the value New or Used in ItemCondition.

Set IncludeCondition to true.

Specify the word "New" or "Used" (or the equivalent in your language) in Query.

Set SearchFlags to SearchInDescription..

To determine whether an item is new or used, the ItemCondition filter checks whether the seller has specified the Item Condition in the listing's Item Specifics. It doesn't check the title or the seller's customized description.

This filter will also return all items for which the seller hasn't specified any Item Condition in the Item Specifics at all (because we don't know whether the item is new or used).

To see the item's condition (if any) in the results, also specify IncludeCondition as true. If the condition is specified in the item, it's returned in ItemSpecific.

If an item in the response has no ItemSpecific node, you can check the title for the word "New" or "Used" (or the equivalent in your language) in case the seller specified the condition there instead.

When you pass the condition in Query, you only find items with that value in the title (which could exclude many new or used items.) If you set SearchFlags to SearchInDescription, eBay will also search in the item description. In many categories, eBay will also search the item condition attribute as part of the SearchInDescription search.

Searching by Number of Bids

You can filter items by the number of bids made on the items. Specifically, you can set a minimum or maximum number of bids, or both. BidRange.MinimumBidCount is used to set a minimum number of bids; BidRange.MaximumBidCount is used to set a maximum.

Searching by Price Range

Use PriceRangeFilter to specify a price range. If you set this property, then the current price of an item must fall within the range to be returned in the GetSearchResults result set.

PriceRangeFilter is of type PriceRangeFilterType. Use the PriceRangeFilterType.MaxPrice property to specify a maximum price and the PriceRangeFilterType.MinPrice property to specify a minimum price. The maximum and minimum price properties can be used together to define a range within which item prices must be. Or they can be used singly to specify just a maximum price or just a minimum price. For example, if a value is specified for PriceRangeFilterType.MaxPrice but not for PriceRangeFilterType.MinPrice, then an item listing is returned if the current price is no greater than the value specified in PriceRangeFilterType.MaxPrice—no matter how low the item listing's price is.

Distance-Based Searches

Use the ProximitySearch property to limit the search to those items within a specified distance of a particular postal code. The items that are searched are those for which the zip or postal code of their location has been provided.

Searching By Listing Type

The ItemTypeFilter property is used to filter items based on the listing type. The ItemTypeFilter property takes precedence over other, related filters.

Note: If you use the deprecated StoresFixedPrice input field (in older versions of the schema) you must change to using values in ItemTypeFilter instead of StoresFixedPrice. For more information, see the following: Knowledge Base Article on Replacing StoresFixedPrice Using ItemTypeFilter https://ebay.custhelp.com/cgi-bin/ebay.cfg/php/enduser/std_adp.php?p_faqid=595

Additionally, within the ItemTypeFilter property, if you currently are using the AllItems filter of ItemTypeFilterCodeType, it is recommended that eventually you use the AllItemTypes filter instead. Unlike in the case of the AllItems filter, AllFixedPriceItemTypes enables you to retrieve fixed-price items that include StoresFixedPrice items regardless of the site default.

The annotations for ItemTypeFilterCodeType contain information about each filter in ItemTypeFilterCodeType. For example, you can use AuctionItemsOnly to limit the result set to just competitive-bid item listings (Chinese and real estate auctions). A value of AllFixedPriceItemTypes retrieves fixed-priced items.

For searches related to store inventory items, you can search for only Store Inventory items. Specifically, use StoreInventoryOnly to only retrieve listings for which ListingType is StoresFixedPrice. Additionally, you can use FixedPriceExcludeStoreInventory to exclude listings that have ListingType set to StoresFixedPrice or exclude listings that have ListingType set to AdType, and exclude auction listings in which BuyItNowEnabled is false. You can use ExcludeStoreInventory to exclude listings that have ListingType set to StoresFixedPrice.

The StoreSearchFilter filter is unaffected by use of ItemTypeFilterCodeType, unless a value in ItemTypeFilterCodeType (such as ExcludeStoreInventory) conflicts with StoreSearchFilter.

Searching for Gallery Listings

Use the SearchType property to limit the result set to just those items listed or featured in the Gallery. SearchType is of type SearchTypeCodeType. See that code list for all possible values and the definitions of each. Use a value of Gallery to limit the result set to just those items listed in or featured in the Gallery. A value of All returns all items, Gallery and non-Gallery alike.

Including or Excluding Sellers

Use the UserIdFilter property to limit the items returned to just those listed by one or more sellers or those not listed by one or more sellers.

You can use UserIdFilter with many other filters, including PriceRangeFilter, SearchFlags, CharityID, CategoryID, and SearchLocationFilter.Currency.

UserIdFilter is of type UserIdFilterType, and has two properties: UserIdFilterType.IncludeSellers and UserIdFilterType.ExcludeSellers (each of type UserIDType). Set UserIdFilterType.IncludeSellers to a list of one or more user IDs of sellers to filter by. Set UserIdFilterType.ExcludeSellers to a list of user IDs for sellers the returned items cannot have been listed by.

You cannot set both the include-seller and exclude-seller filters in the same call. If a list of sellers to include is specified, the list automatically excludes any other sellers. If a call specifies a list of sellers to include and a list of sellers to exclude, an error is returned.

Searching by Item Location

Use the SearchLocationFilter property to limit the items returned in the result set to just those meeting location criteria. SearchLocationFilter is of type SearchLocationFilterType. Specify a country code for the SearchLocationFilterType.CountryCode property to limit the items returned to just those listed on a particular eBay site.

Use the SearchLocationFilterType.ItemLocation property to modify how the value specified in SearchLocationFilterType.CountryCode is used. A value of ItemAvailableIn specifies that the items should be available in the specified country and a value of ItemLocatedIn specified that the items should be located in that country. Use the SearchLocationFilterType.SearchLocation property to specify a search location (region ID or site location). Use the Currency property to limit the items returned to just those listed with a particular currency. See the code list ItemLocationCodeType for possible values.

In search results, using ItemType.Country and ItemType.Location, you can determine where an item is located. Additionally, ItemType.PostalCode indicates the postal code of the place where the item is located.

Searching for Listings that Appear in eBay Stores

Use StoreSearchFilter to filter with eBay Stores as a criterion. StoreSearchFilter is of type SearchStoreFilterType, which has two properties: StoreName and StoreSearch. Specify a store name in StoreSearchFilter.StoreName to limit items to those in one eBay Store. You can use StoreSearchFilter.StoreSearch to limit items to particular listing types within a store. See the code list StoreSearchCodeType for possible values for StoreSearch.

You can use StoreSearchFilter with many other filters, including PriceRangeFilter, UserIdFilter, SearchLocationFilter, CharityID, and SearchType.

If you want to search in all stores, you can use other StoreSearch values, such as BuyItNowItemsInAllStores (and do not specify a value in StoreName).

Search results include Item.Storefront, which contains store-related information, including Item.StoreURL and Item.StoreName.

Searching for Items that Have Changed

Use the ModTimeFrom filter to limit the results to items that have changed since a point in time. (There is no "ModTimeTo" filter. The modification time window ends with the current time.)

An application that always searches for the same kinds of items could retrieve all matching items initially, and then later only retrieve active items whose status has changed since the initial search. For this use case, the application could set the ModTimeFrom value to the eBay official time returned from the previous search.

Please note that time values that are returned in the data from GetSearchResults (e.g., StartTime and the eBay time) are in GMT. See Time Values for information on converting between time zones.

These are a few of the common changes that result in matches when you use the ModTimeFrom filter:

The ModTimeFrom filter restricts the response to active items. That is, when you use this filter, no completed items are returned (unlike modification filters used with other calls like GetSellerEvents). For example, the following changes do not result in matches:

Item changes are processed by means of back-end batch jobs, and the time it takes for items to be indexed can vary. This means the list of modified items returned from GetSearchResults may not be 100% current. For example, if a user places a bid on an item a few seconds before you call GetSearchResults or if a new item is listed a few seconds before the call is sent, the item might not appear in the results. Even when you set ModTimeFrom to the eBay time value returned from the previous search, it is still possible that some changed items will be missed. If your application depends on accurately tracking the current status of items, use a different item-retrieval call like GetSellerList instead.

Searching for Listings that End within a Time Range

Some users are interested in searching for items that end within a particular time range. For example, users who are comparing many items might not be interested in items that end within the next few seconds. Other users may be interested only in items that end within the next hour.

To limit search results to items that end within a particular time range (from the current time to any time in the future), use the EndTimeFrom and EndTimeTo filters.

For example, an application could provide search options that include a drop-down list to allow the user to search for items that end within a predefined time range, such as 1 hour, 2 hours, 3 hours, or any number of days from now. For each option, the application would add the selected number hours to the current time (in GMT), and then pass the resulting value in the request.

Please note that the EndTime value in the data returned from GetSearchResults is in GMT. See Time Values for information on converting between time zones.

Controlling the Way Data Is Returned

In addition to filters, you can specify certain properties to control the way data is returned. These do not control which data is returned, but rather how it is sorted and the volume of the response.

Sorting Search Results

Use the Order property of GetSearchResults to specify the order in which the returned items are sorted. For example, you can sort by the country the items are in. You can sort by Best Match. The possible values for the Order property are in the SearchSortOrder code list. For more information, see the Order input field in the GetSearchResults topic:

You can use a value of SortByEndDate to sort the item listings by their end times. Use a value of SortByStartDate to sort returned items by their start times.

Use a value of BestMatchSort to sort by Best Match, which is based on community buying activity and other relevance-based factors. You can use a value of BestMatchCategoryGroup to group Best Match search results by category. If you use the BestMatchCategoryGroup value to order your results, you can also specify the maximum number of groups returned and the maximum number of entries returned per group within the group element of the call. Note that there will be significanty fewer results returned with a BestMatchCategoryGroup sort because the results account for Best Matches in lower-level as well as higher-level categories.

There is not a direct correlation between the number of results returned in a regular sort or the number of results returned with a BestMatchSort, and the results that are returned by the BestMatchCategoryGroup sort. You should not receive more than 2 pages of results with a BestMatchCategoryGroup sort. See the GroupCategoryID element in ItemType, within the schema information, for more detailed information about the way results are returned with an Order value of BestMatchCategoryGroup.

In general, when you are not searching within Stores, Store Inventory listings are returned after Chinese, basic Fixed Price, and other listing types. Very rarely, a Store Inventory Item can appear in the results before a regular listing, if you are using a BestMatchCategoryGroup sort.

Use a value of SortByCurrentBid to sort the items by the current bid price (purchase price for fixed-price listings). Use a value of SortByListingDate to sort by listing start dates (in descending order). Use a value of SortByCurrentBidAsc to sort by current bid price, in ascending order or SortByCurrentBidDesc to sort by current bid price in descending order.

Reducing ItemType fields Returned

Use the GranularityLevel property of GetSearchResults to reduce the Item fields returned. Specifically, use the Coarse value if you want only the following fields to be returned for items (if applicable to the result set): ItemID, Title, ListingType, and various other fields (listed in the eBay Trading API Call Reference), plus any fields resulting from the detail level you specify.

Paginating Search Results

Use the Pagination property and its child elements to break the items matching the search criteria down into smaller subsets, or "pages" of data.

The Pagination.EntriesPerPage property specifies the maximum number of items to return in any given call. The Pagination.PageNumber property specifies which "page" of data to return in the current call.

There are corresponding properties in the GetSearchResults response object that are used for paginating data. The PaginationResult.TotalNumberOfEntries property indicates the total number of items matching the input search criteria that could be returned (with one or multiple calls). If the value specified in Pagination.EntriesPerPage is less than that returned in PaginationResult.TotalNumberOfEntries, then it will take more than one call to retrieve all of the matching items. The PaginationResult.TotalNumberOfPages property indicates the total number of calls that would be required to retrieve all of the matching items. The value specified in the Pagination.PageNumber property of GetSearchResults indicates where in the sequence of multiple calls the application is, relative to the number returned in PaginationResult.TotalNumberOfPages.


Searching for and Retrieving Items > Searching for Items > Searching for Items by Using a Query
http://developer.ebay.com/DevZone/XML/docs/WebHelp/SearchingForItems-Searching_for_Items_by_Using_a_Query.html
© 2004–2009 eBay Inc. All rights reserved.	Version 623

Searching for Items by Using a Query