GetSearchResultsRequestType
Note: This API call is being deprecated and will not be available after July 1, 2010. The functionality provided by this call will be supported in the new Finding API. If you're building new search applications, we recommend you start with the Finding API.
Retrieves item listings based on keywords you specify. The keywords can include wildcards.

The response is in the form of an array whose size and contents you specify, using a variety of input fields. You can filter the item listings returned using such criteria as the listing category, location, whether the item is listed in an ebay Store, and listing type. You can include or exclude specified sellers.

The call returns those item listings where the keywords appear in the title, subtitle, and (optionally) the description. Some input fields (e.g., Query) are primary search criteria that let you specify data to match in listings. For example, you can search for all listings that include the word "Toy" in the title.

Some fields (e.g., ItemTypeFilter) are secondary search criteria that let you further refine data to match in listings. For example, you can search for all toys that are listed as auctions. In general, the effect of secondary search fields is cumulative (using "AND" logic) unless otherwise specified. Some fields (e.g., TotalOnly) control what is actually returned in the result set. For example, you can search for all toys that are listed as Chinese auctions, but just retrieve the total count (not the listings themselves).

Some fields (e.g., IncludeCondition) affect the data to retrieve for each listing in the result set. For example, for each toy returned in the result, you can also choose to see the toy's new or used condition.

Some fields (e.g., Order) control the way the listings are organized in the response. For example, you can retrieve all the toy listings in chronological order, with the newest one first. Use the DetailLevel ItemReturnCategories to return the primary category and, if applicable, the secondary category.

Use a DetailLevel value of ItemReturnAttributes (or ReturnAll) to return summary Item Specifics (only returned for categories that support summary Item Specifics in search results).

If you are not using the BestMatch search option, the API search results may not match the search results returned by the eBay website.

Not applicable to Half.com.
Fields
AdFormat ( boolean )
AffiliateTrackingDetails ( AffiliateTrackingDetailsType )
BidRange ( BidRangeType )
Categories ( RequestCategoriesType )
CategoryID ( string )
CharityID ( int )
EndTimeFrom ( dateTime )
EndTimeTo ( dateTime )
ExpandSearch ( boolean )
ExternalProductID ( ExternalProductIDType )
FreeShipping ( boolean )
GranularityLevel ( GranularityLevelCodeType )
Group ( GroupType )
HideDuplicateItems ( boolean )
IncludeCondition ( boolean )
IncludeFeedback ( boolean )
IncludeGetItFastItems ( boolean )
ItemCondition ( ItemConditionCodeType )
ItemTypeFilter ( ItemTypeFilterCodeType )
LocalSearchPostalCode ( string )
Lot ( boolean )
MaxRelatedSearchKeywords ( int )
ModTimeFrom ( dateTime )
MotorsGermanySearchable ( boolean )
Order ( SearchSortOrderCodeType )
Pagination ( PaginationType )
PaymentMethod ( PaymentMethodSearchCodeType )
PriceRangeFilter ( PriceRangeFilterType )
ProductID ( string )
ProximitySearch ( ProximitySearchType )
Quantity ( int )
QuantityOperator ( QuantityOperatorCodeType )
Query ( string )
SearchFlags ( SearchFlagsCodeType )
SearchLocationFilter ( SearchLocationFilterType )
SearchRequest ( SearchRequestType )
SearchType ( SearchTypeCodeType )
SellerBusinessType ( SellerBusinessCodeType )
StoreSearchFilter ( SearchStoreFilterType )
TicketFinder ( TicketDetailsType )
TotalOnly ( boolean )
UserIdFilter ( UserIdFilterType )

AdFormat ( boolean ) [0..1]
Restricts listings to return only items that have the Ad Format feature. If true, the values of ItemTypeFilter and StoreSearchFilter are ignored (if they are specified). That is, "AND" logic is not applied.
See the Field Index to learn which calls use AdFormat.

AffiliateTrackingDetails ( AffiliateTrackingDetailsType ) [0..1]
Container for affiliate tags. If you use affiliate tags, it is possible to get affiliate commissions based on calls made by your application. (See the eBay Partner Network for information about commissions.) Affiliate tags enable the tracking of user activity. You can use child tags of AffiliateTrackingDetails if you want call output to include a string that includes affiliate tracking information.
See the Field Index to learn which calls use AffiliateTrackingDetails.

BidRange ( BidRangeType ) [0..1]
Limits the results to items with a minimum or maximum number of bids. You also can specify a bid range by specifying both a minimum and maximum number of bids in one call.
See the Field Index to learn which calls use BidRange.

Categories ( RequestCategoriesType ) [0..1]
Retrieves statistical (histogram) information about categories that contain items that match the query. Can also cause the result to include information about buying guides that are associated with the matching categories. Does not control the set of listings to return or the details to return for each listing.
See the Field Index to learn which calls use Categories.

CategoryID ( string ) [0..1]
Limits the result set to items in the specified category. If no category ID is specified, all categories are searched by default.

Note: CategoryID does not control whether you will see the item's categories in the response. Set the value of DetailLevel to ItemReturnCategories to retrieve each item's primary category and secondary category (if any) in the response.

If the specified category ID doesn't match an existing category for the site, an invalid-category error message is returned. Here are a few ways to determine valid categories:
- Use the Categories input field to retrieve matching categories, and then submit the request again with one of those categories.
- Find items in all categories but set DetailLevel to ItemReturnCategories, determine the primary (or secondary) category ID for a similar item in the results, and then submit the request again with that category ID.
- Use another call like GetCategories or GetSuggestedCategories to find a valid category ID.

You must pass ProductID, Query, ExternalProductID, or CategoryID in the request. CategoryID can be used in combination with Query. It is not allowed with ExternalProductID or ProductID. If you pass CategoryID without Query, it must specify a leaf category ID. That is, it cannot be a meta-category ID (e.g., 267 for "Books").
See the Field Index to learn which calls use CategoryID.

CharityID ( int ) [0..1]
Restricts listings to return only items that support the specified nonprofit charity organization. Retrieve CharityID values with GetCharities.
See the Field Index to learn which calls use CharityID.

EndTimeFrom ( dateTime ) [0..1]
Limits the results to items ending within a time range. EndTimeFrom specifies the beginning of the time range. Specify a time in the future. If you specify a time in the past, the current time is used. If specified, EndTimeTo must also be specified (with a value equal to or later than EndTimeFrom). Specify the time in GMT. Cannot be used with the ModTimeFrom filter.
See the Field Index to learn which calls use EndTimeFrom.

EndTimeTo ( dateTime ) [0..1]
Limits the results to items ending within a time range. EndTimeTo specifies the end of the time range. If specified, EndTimeFrom must also be specified (with a value equal to or earlier than EndTimeTo). Specify the time in GMT. Cannot be used with the ModTimeFrom filter.
See the Field Index to learn which calls use EndTimeTo.

ExpandSearch ( boolean ) [0..1]
Expands search results when a small result set is returned. For example, on the US site (site ID 0), if a search would normally result in fewer than 10 items, then if you specify true for this tag, 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 (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). Maximum number of items returned in each expansion container is 6 to 10.
See the Field Index to learn which calls use ExpandSearch.

ExternalProductID ( ExternalProductIDType ) [0..1]
An exclusive query to only retrieve items that were listed with the specified ISBN or UPC. Only applicable for items that were listed with Pre-filled Item Information in media categories (Books, Music, DVDs and Movies, and Video Games). You must pass ProductID, Query, ExternalProductID, or CategoryID in the request. If you use ExternalProductID, do not use Query, ProductID, or CategoryID.
See the Field Index to learn which calls use ExternalProductID.

FreeShipping ( boolean ) [0..1]
If true, only items with free shipping for the user's location are returned. The user's location is determined from the site ID specified in the request. If false, no filtering is done via this attribute. A listing is not considered a free shipping listing if it requires insurance or requires pick up or requires a shipping surcharge.
See the Field Index to learn which calls use FreeShipping.

GranularityLevel ( see GranularityLevelCodeType for possible values ) [0..1]
Optional tag that currently accepts only one value for this call: Coarse. Other values return an error. If you specify Coarse, the call returns the fields shown in the GranularityLevel table plus any tags resulting from the detail level you specify. Controls the fields to return for each listing (not the set of listings that match the query).
See the Field Index to learn which calls use GranularityLevel.

Group ( GroupType ) [0..1]
You can group Best Match search results by category by specifying BestMatchCategoryGroup in the Order field. When you specify BestMatchCategoryGroup in the Order field, you can also specify Group.MaxEntriesPerGroup and/or Group.MaxGroups. When you specify BestMatchCategoryGroup in the Order field, there will be fewer results returned because Best Matches in lower-level (leaf) categories and higher-level categories are taken into account. There is not a direct correlation between the number of items returned in a regular sort (or in a BestMatch sort) and the number of items that are returned when you specify BestMatchCategoryGroup in the Order field. When you specify BestMatchCategoryGroup in the Order field, not more than 2 pages of results are returned. See also the GroupCategoryID element in ItemType.
See the Field Index to learn which calls use Group.

HideDuplicateItems ( boolean ) [0..1]
Specifies whether or not to remove duplicate items from search results. When set to true, and there are duplicate items for an item in the search results, the subsequent duplicates will not appear in the results. Item listings are considered duplicates in the following conditions:
  • Items are listed by the same seller
  • Items have exactly the same item title
  • Items have similar listing formats
    • Auctions: Auction Items, Auction BIN items, Multi-Quantity Auctions, and Multi-Quantity Auctions BIN items
    • Fixed Price: Fixed Price, Multi-quantity Fixed Price, Fixed Price with Best Offer, and Store Inventory Format items
    • Classified Ads

For Auctions, items must also have the same price and number of bids to be considered duplicates.
Filtering of duplicate item listings is not supported on all sites.
See the Field Index to learn which calls use HideDuplicateItems.

IncludeCondition ( boolean ) [0..1]
If true, each item in the result set can also include the item condition (e.g., New or Used) in the ItemSpecific property of the response. An item only includes the condition in the response if the seller filled in the Item Condition in the Item Specifics section of the listing. (That is, the condition is not returned if the seller only put the word "New" in the listing's title.)

Controls the details to return for each listing (not the set of listings that match the query).

To control whether to retrieve only new or used items, see ItemCondition (or SearchRequest).
See the Field Index to learn which calls use IncludeCondition.

IncludeFeedback ( boolean ) [0..1]
If true, each item in the result set also includes information about the seller's feedback. Controls the details to return for each listing (not the set of listings that match the query).
For GetSearchResults, if set to true will also return the seller's User ID.
See the Field Index to learn which calls use IncludeFeedback.

IncludeGetItFastItems ( boolean ) [0..1]
When passed with a value of true, limits the results to Get It Fast listings.
See the Field Index to learn which calls use IncludeGetItFastItems.

ItemCondition ( see ItemConditionCodeType for possible values ) [0..1]
Limits the results to new or used items, plus items that have no condition specified.

Matches the new or used condition that the seller specified in the Item Specifics section of the listing. (That is, this won't specifically match on items where the seller only put the word "New" in the listing's title.)

Only applicable to sites and categories that support a sitewide (global) item condition. For example, the US site does not currently support this. See GetCategory2CS. To search for the item condition on the US site, use a product finder instead (see SearchRequest).
See the Field Index to learn which calls use ItemCondition.

ItemTypeFilter ( see ItemTypeFilterCodeType for possible values ) [0..1]
Filters items based on the ListingType set for the items. If ItemTypeFilter is not specified (or if the AllItemTypes value of ItemTypeFilter is specified), all listing types can be returned unless another relevant filter is specified.
See the Field Index to learn which calls use ItemTypeFilter.

LocalSearchPostalCode ( string ) [0..1]
Include local items in returning results near this postal code. This postal code is the basis for local search.
See the Field Index to learn which calls use LocalSearchPostalCode.

Lot ( boolean ) [0..1]
Limits the results to only those listings for which Item.LotSize is 2 or greater.
See the Field Index to learn which calls use Lot.

MaxRelatedSearchKeywords ( int ) [0..1]
The maximum number of related keywords to be retrieved. Use this field if you want the search results to include recommended keywords (that is, keywords matching one or more of the original keywords) in a RelatedSearchKeywordArray container. A value of 0 (the default) means no related search information is processed.
See the Field Index to learn which calls use MaxRelatedSearchKeywords.

ModTimeFrom ( dateTime ) [0..1]
Limits the results to active items whose status has changed since the specified time. Specify a time in the past. Time must be in GMT. Cannot be used with the EndTime filters.
See the Field Index to learn which calls use ModTimeFrom.

MotorsGermanySearchable ( boolean ) [0..1]
Limits the results based on each item's eligibility to appear on the mobile.de site. If false, excludes eligible items from search results. If true, queries for eligible items only. If not specified, the search results are not affected. Only applicable for items listed on the eBay Germany site (site ID 77) in subcategories of mobile.de search-enabled categories.
See the Field Index to learn which calls use MotorsGermanySearchable.

Order ( see SearchSortOrderCodeType for possible values ) [0..1]
Specifies the order in which listings are returned in a result set. Listings may be sorted by end time, start time, and in other ways listed in the SearchSortOrderCodeType. Controls the way the listings are organized in the response (not the details to return for each listing). For most sites, the default sort order is by items ending soonest. Store Inventory listings are usually returned after other listing types, regardless of the sort order.
See the Field Index to learn which calls use Order.

Pagination ( PaginationType ) [0..1]
Controls the pagination of the result set. Child elements specify the maximum number of item listings to return per call and which page of data to return. Controls the way the listings are organized in the response (not the details to return for each listing).
See the Field Index to learn which calls use Pagination.

PaymentMethod ( see PaymentMethodSearchCodeType for possible values ) [0..1]
Limits the results to items that accept a specific payment method or methods.
See the Field Index to learn which calls use PaymentMethod.

PriceRangeFilter ( PriceRangeFilterType ) [0..1]
Limits the result set to just those items where the price is within the specified range. The PriceRangeFilterType includes a minimum and a maximum price.
See the Field Index to learn which calls use PriceRangeFilter.

ProductID ( string ) [0..1]
An exclusive query to retrieve items that were listed with the specified eBay catalog product. You must pass ProductID, Query, ExternalProductID, or CategoryID in the request. If you use ProductID, do not use Query, ExternalProductID, or CategoryID.

As of mid-2008, some sites (such as eBay US, Germany, Austria, and Switzerland) are updating, replacing, deleting, or merging some products (as a result of migrating from one catalog data provider to another). If you specify one of these products, the call may return a warning, or it may return an error if the product has been deleted.
See the Field Index to learn which calls use ProductID.

ProximitySearch ( ProximitySearchType ) [0..1]
Limits the result set to just those items whose location is within a specified distance of a postal code. The ProximitySearchType includes a maximum distance and a postal code.
See the Field Index to learn which calls use ProximitySearch.

Quantity ( int ) [0..1]
Limits the results to listings that offer a certain number of items matching the query. If Lot is also specified, then Quantity is the number of lots multiplied by the number of objects in each lot. Use QuantityOperator to specify that you are seeking listings with quantities greater than, equal to, or less than Quantity.
See the Field Index to learn which calls use Quantity.

QuantityOperator ( see QuantityOperatorCodeType for possible values ) [0..1]
Limits the results to listings with quantities greater than, equal to, or less than Quantity. Controls the set of listings to return (not the details to return for each listing).
See the Field Index to learn which calls use QuantityOperator.

Query ( string ) [0..1]
A query that specifies a search string. The search string consists of one or more keywords to search for in the listing title and/or description. 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. Wildcards (e.g., *) are also supported. Be careful when using spaces before or after modifiers and wildcards (+, -, or *). See the eBay Web Services Guide for a list of valid modifiers and examples. Query is not applicable in combination with ExternalProductID or ProductID.
See the Field Index to learn which calls use Query.

SearchFlags ( see SearchFlagsCodeType for possible values ) [0..*]
Secondary search criterion that checks item descriptions for keywords that match the query, limits the search results to only charity items, limits the result set to those items with PayPal as a payment method, and/or provides other criteria to refine the search.
See the Field Index to learn which calls use SearchFlags.

SearchLocationFilter ( SearchLocationFilterType ) [0..1]
Limits the result set to just those items that meet location criteria: listed in a specified eBay site, location where the seller has the item, location from which the user is searching, and/or items listed with a specified currency.
See the Field Index to learn which calls use SearchLocationFilter.

SearchRequest ( SearchRequestType ) [0..1]
A query consisting of a set of attributes (Item Specifics). Use this kind of query to search against the Item Specifics in listings (e.g., to search for a particular shoe size). If the query includes multiple attributes, the search engine will apply "AND" logic to the query and narrow the results. Use GetProductFinder to determine the list of valid attributes and how many are permitted for the specified characteristic set. Retrieves items along with any buying guide details that are associated with the specified product finder. Applicable in combination with the Query argument. Cannot be used in combination with ProductID or ExternalProductID.

If you are searching for tickets, see TicketFinder instead.
See the Field Index to learn which calls use SearchRequest.

SearchType ( see SearchTypeCodeType for possible values ) [0..1]
Limits the listings in the result set based on whether they are in the Gallery. The choices are items in the Gallery or Gallery and non-Gallery items.
See the Field Index to learn which calls use SearchType.

SellerBusinessType ( see SellerBusinessCodeType for possible values ) [0..1]
Limits the results to those of a particular seller business type such as commercial or private. Applies only to the following sites: UK, France, and Germany.
See the Field Index to learn which calls use SellerBusinessType.

StoreSearchFilter ( SearchStoreFilterType ) [0..1]
Limits the result set to just those items that meet criteria related to eBay Stores sellers and eBay Stores. Use this to retrieve items listed in a particular seller's eBay Store or in all store sellers' eBay Stores. This filter always causes item description text to be searched with the string specified in the Query field. That is, StoreSearchFilter forces the type of search that would have occurred if you had specified SearchInDescription in the SearchFlags field.
See the Field Index to learn which calls use StoreSearchFilter.

TicketFinder ( TicketDetailsType ) [0..1]
Searches for event ticket listings only. If specified, this cannot be empty. For example, to search for all tickets (with no event, date, city, or quantity constraints), specify EventType with a value of Any. If specified, Query is optional. Query is useful when the user wants to search for a particular event name (like "eric clapton") or a venue that might be included in the listing title. If TicketFinder and SearchRequest are both specified in the same request, SearchRequest is ignored.
See the Field Index to learn which calls use TicketFinder.

TotalOnly ( boolean ) [0..1]
Retrieves the total quantity of matching items, without returning the item data. See PaginationResult.TotalNumberOfEntries in the response. If TotalOnly and Categories.CategoriesOnly are both specified in the request and their values are inconsistent with each other, TotalOnly overrides Categories.CategoriesOnly. That is, if TotalOnly is true and Categories.CategoriesOnly is false, the results include matching categories but no item data or buying guides. If TotalOnly is false and Categories.CategoriesOnly is true, the results include matching categories, item data, and buying guides. If TotalOnly is not specified, it has no logical effect.
See the Field Index to learn which calls use TotalOnly.

UserIdFilter ( UserIdFilterType ) [0..1]
Limits the the result set to just those items listed by one or more specified sellers or those items not listed by the one or more specified sellers.
See the Field Index to learn which calls use UserIdFilter.

This document was generated with a customized version of the apireferencedocs tool.

© 2005–2009 eBay, Inc. All rights reserved. This documentation and the API may only be used in accordance with the eBay Developers Program and API License Agreement.