FindItemsAdvancedRequestType
Searches for items based on a variety of input fields. Enables you to specify what item data is returned. Returns detailed information about items.

If you are not using the BestMatch search option, the API search results may not match the search results returned by the eBay website.
Fields
BidCountMax ( int )
BidCountMin ( int )
CategoryHistogramMaxChildren ( int )
CategoryHistogramMaxParents ( int )
CategoryID ( string )
CategoryIDExclude ( string )
CharityID ( int )
Condition ( ItemConditionCodeType )
Currency ( CurrencyCodeType )
DescriptionSearch ( boolean )
EndTimeFrom ( dateTime )
EndTimeTo ( dateTime )
ExcludeFlag ( ExcludeFlagCodeType )
FeedbackScoreMax ( int )
FeedbackScoreMin ( int )
GroupMaxEntries ( int )
GroupsMax ( int )
HideDuplicateItems ( boolean )
IncludeSelector ( string )
ItemLocationRegion ( ItemLocationRegionCodeType )
ItemsAvailableTo ( CountryCodeType )
ItemsLocatedIn ( CountryCodeType )
ItemSort ( SimpleItemSortCodeType )
ItemType ( ItemTypeCodeType )
MaxDistance ( int )
MaxEntries ( int )
ModTimeFrom ( dateTime )
PageNumber ( int )
PaymentMethod ( PaymentMethodSearchCodeType )
PostalCode ( string )
PreferredLocation ( PreferredLocationCodeType )
PriceMax ( AmountType (double) )
PriceMin ( AmountType (double) )
ProductID ( ProductIDType (string) )
Quantity ( int )
QuantityOperator ( QuantityOperatorCodeType )
QueryKeywords ( string )
SearchFlag ( SearchFlagCodeType )
SellerBusinessType ( SellerBusinessCodeType )
SellerID ( string )
SellerIDExclude ( string )
ShippingLocation ( CountryCodeType )
ShippingPostalCode ( string )
SortOrder ( SortOrderCodeType )
StoreName ( string )
StoreSearch ( StoreSearchCodeType )

BidCountMax ( int ) [0..1]
Limits the results to items with a maximum number of bids.
Not supported when CategoryID is specified in the request, and QueryKeywords is not included in the request.
See the Field Index to learn which calls use BidCountMax.

BidCountMin ( int ) [0..1]
Limits the results to items with a minimum number of bids.
Not supported when CategoryID is specified in the request, and QueryKeywords is not included in the request.
See the Field Index to learn which calls use BidCountMin.

CategoryHistogramMaxChildren ( int ) [0..1]
Maximum number of matching subcategories to return at each level of the category hierarchy below the root level. If you specify this field along with a category ID, then the response will contain child categories of the category ID you specify and subcategories for each child category.
See the Field Index to learn which calls use CategoryHistogramMaxChildren.

CategoryHistogramMaxParents ( int ) [0..1]
Maximum number of matching categories to return at the highest level (root level) of the category hierarchy (level 1). If you specify this field along with a category ID, then the response will contain child categories of the category ID you specify and subcategories for each child category.
See the Field Index to learn which calls use CategoryHistogramMaxParents.

CategoryID ( string ) [0..1]
Specify CategoryID to restrict your query to a specific category.

If the specified category ID doesn't match an existing category for the site, an invalid-category error message is returned. To determine valid categories:
Use the CategoryHistogram value in the IncludeSelector field to retrieve matching categories. Then make another FindItemsAdvanced call with the ID of a matching category.

FindItemsAdvanced requires that you specify at least one of the following: QueryKeywords, CategoryID, ProductID, or SellerID. CategoryID can be used in combination with QueryKeywords. If you pass CategoryID without QueryKeywords, CategoryID must be a leaf category ID. That is, it cannot be a root-level ID.
See the Field Index to learn which calls use CategoryID.

CategoryIDExclude ( string ) [0..*]
Specify a CategoryIDExclude value in your request if you want search results to be filtered so that the items returned do not include items that belong to the specified category.

CategoryIDExclude is an unbounded field. If you are using a URL, you can separate multiple values with a comma. For example, if you want to specify Records and SuperAudio CDs, specify CategoryIDExclude=306,46354.

If you use CategoryIDExclude, it must be used along with either QueryKeywords, CategoryID, ProductID, or SellerID. You do not need to use the CategoryIDExclude input field every time you use the CategoryID input field.
See the Field Index to learn which calls use CategoryIDExclude.

CharityID ( int ) [0..1]
Limits results to items that support the specified nonprofit charity organization.
See the Field Index to learn which calls use CharityID.

Condition ( see ItemConditionCodeType for possible values ) [0..1]
Limits the results to new OR used items (exclusive, not both), plus items that have no condition specified.
Not supported when CategoryID is specified in the request, and QueryKeywords is not included in the request.
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 the following sites: United Kingdom (UK, site ID 3), Australia (AU, site ID 15), Germany (DE, site ID 77), and India (IN, site ID 203).
See the Field Index to learn which calls use Condition.

Currency ( see CurrencyCodeType for possible values ) [0..1]
Limits the result set to just those items with a specified currency.
See the Field Index to learn which calls use Currency.

DescriptionSearch ( boolean ) [0..1]
Specifies whether you want to include the item's description in a search. Searching the text of the description can take longer than searching without the description. If true, the text of the item's description will be included in the search. If false, the item's description will be excluded from the search.
See the Field Index to learn which calls use DescriptionSearch.

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.

ExcludeFlag ( see ExcludeFlagCodeType for possible values ) [0..*]
Excludes items with the specified flag from the search.
See the Field Index to learn which calls use ExcludeFlag.

FeedbackScoreMax ( int ) [0..1]
Specifies the maximum feedback score of a seller whose items can be included in the response.
See the Field Index to learn which calls use FeedbackScoreMax.

FeedbackScoreMin ( int ) [0..1]
Specifies the mininum feedback score of a seller whose items can be included in the response.
See the Field Index to learn which calls use FeedbackScoreMin.

GroupMaxEntries ( int ) [0..1]
GroupMaxEntries is used when you specify that BestMatch search results are grouped by category (by using BestMatchCategoryGroup in the ItemSort field.) In GroupMaxEntries, you specify the maximum number of entries per group that you want in the search results. 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 ItemSort field. When you specify BestMatchCategoryGroup in the ItemSort field, not more than 2 pages of results are returned. When you specify GroupMaxEntries, specify GroupsMax.
See the Field Index to learn which calls use GroupMaxEntries.

GroupsMax ( int ) [0..1]
GroupsMax is used when you specify that BestMatch search results are grouped by category (by using BestMatchCategoryGroup in the ItemSort field.) In GroupsMax, you specify the maximum number of groups that you want in the search results. 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 ItemSort field. When you specify BestMatchCategoryGroup in the ItemSort field, not more than 2 pages of results are returned. When you specify GroupsMax, specify GroupMaxEntries.
See the Field Index to learn which calls use GroupsMax.

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.

IncludeSelector ( string ) [0..1]
Defines standard subsets of fields to return within the response.

If you don't specify this field, a default set of fields is returned. Click "Detail Controls" below and see "none" for the default fields. If you specify this field, then the set of fields returned includes the default fields. If you specify this field, the additional fields returned can affect the call's response time (performance), including in the case of feedback data.

Applicable values:

•   Details

Include most available fields in the response (except fields that significantly affect the call's performance).

•   SearchDetails

Include additional item information in the response. (This can affect the call's performance.)

•   SellerInfo

Include information about the seller in the response.

•   ItemSpecifics

Include ItemSpecifics in the response. This only returns Item Specifics (if any) that are applicable to search results (not all of a listing's Item Specifics).

•   ExpansionItemCount

Include the counts of items that would be returned with expansions.

•   CategoryHistogram

Include a CategoryHistogram container with information about categories that match your search (up to 2 levels).


Use a comma to specify multiple values. (In this case, the results are cumulative.) See "FindItemAdvanced Samples" for an example of how to use this field.

See "Detail Controls" for a complete list of fields that can be returned for each selector. IncludePictureURL, return all picture URLs of the items, 12 at maximum.
See the Field Index to learn which calls use IncludeSelector.

ItemLocationRegion ( see ItemLocationRegionCodeType for possible values ) [0..1]
Allows you to search for items in a specified region.
See the Field Index to learn which calls use ItemLocationRegion.

ItemsAvailableTo ( see CountryCodeType for possible values ) [0..1]
Limits the result set to just those items available to the specified country.
Not supported when CategoryID is specified in the request, and QueryKeywords is not included in the request.
See the Field Index to learn which calls use ItemsAvailableTo.

ItemsLocatedIn ( see CountryCodeType for possible values ) [0..1]
Limits the result set to just those items located in the specified country.
Not supported when CategoryID is specified in the request, and QueryKeywords is not included in the request.
See the Field Index to learn which calls use ItemsLocatedIn.

ItemSort ( see SimpleItemSortCodeType for possible values ) [0..1]
Sorts search results based on the value you specify. See the SortOrder field for values for specifying that results are returned in ascending or descending order. (By default, results are returned in descending order.)
See the Field Index to learn which calls use ItemSort.

ItemType ( see ItemTypeCodeType for possible values ) [0..1]
Filters items based on criteria related to the listing type of items.
See the Field Index to learn which calls use ItemType.

MaxDistance ( int ) [0..1]
The maximum distance from the postal code specified in the PostalCode field. (The PostalCode field contains the postal code of the buyer.) The MaxDistance unit (miles or kilometers) varies by site. If the country whose site you are searching, e.g. India, uses kilometers, then the MaxDistance unit is kilometers. Otherwise, e.g. if the country is US or UK, The search behavior depends on the following combination of MaxDistance and Postal Code values:

If MaxDistance is set to a value other than 0, and a postal code is entered, the search will retrieve items at the specified distance from the postal code entry (this is the default behavior).

If MaxDistance is set to 0, and no postal code is entered, the postal code search location criteria will be ignored.

If MaxDistance is set to 0, and one postal code is entered, only items within the limits of that postal code will be returned.

If MaxDistance is set to 0, and several postal codes are entered, items within any of the postal codes will be returned, but only the first postal code entered will be used to calculate shipping cost and to sort by distance.
See the Field Index to learn which calls use MaxDistance.

MaxEntries ( int ) [0..1]
Specifies the maximum number of entries to be returned in a single call. If the number of available items is less than the value you specify, the lower number is returned. If you want the response to contain only the total number of items matching the query, specify a MaxEntries value of 0. Note that if a query normally would return more than 10,000 items, only the first 10,000 items are returned. This limit is independent of the value you specify in the MaxEntries field.
See the Field Index to learn which calls use MaxEntries.

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.

PageNumber ( int ) [0..1]
Specifies the number of the page of data to return in the current call. Specify a positive value equal to or lower than the number of pages available (which you determine by examining the results of your initial request).
See the Field Index to learn which calls use PageNumber.

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

PostalCode ( string ) [0..1]
The postal code where the buyer is located. The search behavior depends on the combination of MaxDistance and Postal Code values. See MaxDistance element for details.
See the Field Index to learn which calls use PostalCode.

PreferredLocation ( see PreferredLocationCodeType for possible values ) [0..1]
Specifies the criteria for filtering search results by site, where site is determined by the site ID in the request.
See the Field Index to learn which calls use PreferredLocation.

PriceMax ( AmountType (double) ) [0..1]
Specifies the maximum current price an item can have to be included in the response. If the request is made using a URL, must include a Value field, as specified in the following URL snippet: PriceMax.Value=500. Optionally, you can also specify a currency ID, e.g., as part of a URL, PriceMax.currencyID=EUR. Use PriceMax to specify a maximum price or use PriceMax with PriceMin to specify a price range.
See the Field Index to learn which calls use PriceMax.

PriceMin ( AmountType (double) ) [0..1]
Specifies the minimum current price an item listing can have to be included in the searches result set. Use alone to specify a minimum price or with MaxPrice to define a range the items' prices must be. If the request is made using a URL, must include a Value field, as specified in the following URL snippet: PriceMin.Value=400. Optionally, you can also specify a currency ID, e.g., as part of a URL, PriceMin.currencyID=EUR.
See the Field Index to learn which calls use PriceMin.

ProductID ( ProductIDType (string) ) [0..1]
You can use this input field to search by ISBN, UPC, EAN, or eBay Product Reference ID, as in the following examples. To search using an ISBN, specify ProductID.Type=ISBN and set ProductID.Value to an ISBN value. To search using an eBay Product Reference ID, specify ProductID.Type=Reference and set ProductID.Value to an eBay Product Reference ID value. If you do not know the eBay Product Reference ID of a product, use FindProducts to retrieve the desired eBay Product Reference ID. FindItemsAdvanced requires that you specify at least one of the following: QueryKeywords, CategoryID, ProductID, or SellerID. If you use the ProductID field, do not use QueryKeywords, CategoryID, or SellerID.
Not supported when CategoryID is specified in the request, and QueryKeywords is not included in the request.
See the Field Index to learn which calls use ProductID.

Quantity ( int ) [0..1]
Limits the results to listings that offer a certain number of items matching the query. The Quantity field is used with QuantityOperator to specify that you are seeking listings with quantities greater than, equal to, or less than the value you specify in Quantity.
Not supported when CategoryID is specified in the request, and QueryKeywords is not included in the request.
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 the value you specify in Quantity.
Not supported when CategoryID is specified in the request, and QueryKeywords is not included in the request.
See the Field Index to learn which calls use QuantityOperator.

QueryKeywords ( string ) [0..1]
A query that specifies a string for searching titles of items on eBay. If you are using a URL, then to search for multiple words, use "%20". For example, use Harry%20Potter to search for items containing those words in any order. You can incorporate wildcards into a multi-word search, as in the following: ap*%20ip*. 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. FindItemsAdvanced requires that you specify at least one of the following: QueryKeywords, CategoryID, ProductID, or SellerID.
See the Field Index to learn which calls use QueryKeywords.

SearchFlag ( see SearchFlagCodeType for possible values ) [0..*]
Search for charity listings, free-shipping listings, and listings with other features.
See the Field Index to learn which calls use SearchFlag.

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. Thus, this input filter is only available for sites that have business seller features enabled.
Not supported when CategoryID is specified in the request, and QueryKeywords is not included in the request.
See the Field Index to learn which calls use SellerBusinessType.

SellerID ( string ) [0..*]
The ID of a specific seller. Specify this value if you want search results to be filtered so that the items returned are only items sold by a specific seller or by specific sellers. SellerID is an unbounded field. If you are using a URL, and you want to specify multiple values, use a comma. For example, to specify FavSellerBlue and FavSellerGreen, specify SellerID=FavSellerBlue,FavSellerGreen. FindItemsAdvanced requires that you specify at least one of the following: QueryKeywords, CategoryID, ProductID, or SellerID. If you want Store Inventory format (StoresFixedPrice) items to be returned, you must also specify the AllItemTypes value in the ItemType field. The value you specify in SellerID is ignored if it is invalid. You can specify a maximum of 100 sellers.
Not supported when CategoryID is specified in the request, and QueryKeywords is not included in the request.
See the Field Index to learn which calls use SellerID.

SellerIDExclude ( string ) [0..*]
Specify this value if you want search results to be filtered so that the items returned do not include items sold by a specific seller or by specific sellers. The SellerIDExclude input field need not be used if you specified the SellerID input field. SellerIDExclude is an unbounded field. If you are using a URL, and you want to specify multiple values, use a comma. For example, if you want to specify FavSellerBlue and FavSellerGreen, specify SellerIDExclude=FavSellerBlue,FavSellerGreen. You can specify a maximum of 100 sellers.
Not supported when CategoryID is specified in the request, and QueryKeywords is not included in the request.
See the Field Index to learn which calls use SellerIDExclude.

ShippingLocation ( see CountryCodeType for possible values ) [0..1]
ShippingLocation should be used together with PostalCode for shipping cost calculations. The items returned are within the specified postal code.
See the Field Index to learn which calls use ShippingLocation.

ShippingPostalCode ( string ) [0..1]
This postal code is for international shipping cost calculations. This should be a valid code within the country specified as the ShippingLocation.
See the Field Index to learn which calls use ShippingPostalCode.

SortOrder ( see SortOrderCodeType for possible values ) [0..1]
Sorts search results in ascending or descending order, in conjunction with the value you specify in ItemSort. The default is descending order. For example, for the ItemSort value of BestMatch (the default), the most relevant items are returned first, because the default SortOrder value is Descending. Please note that in the case of an ItemSort value of EndTime (to sort items by end time), you must specify a SortOrder value of Ascending. These parameters result in a sort of items by those ending soonest (from the time of the call), before those ending later.
Not supported when CategoryID is specified in the request, and QueryKeywords is not included in the request.
See the Field Index to learn which calls use SortOrder.

StoreName ( string ) [0..1]
The name of the eBay Store in which the item is listed.

Not supported when CategoryID is specified in the request, and QueryKeywords is not included in the request.

Note: Store names are case sensitive. Also, if the store name contains an ampersand (&), you must use the character entity reference (&) in its place.
See the Field Index to learn which calls use StoreName.

StoreSearch ( see StoreSearchCodeType for possible values ) [0..1]
Specifies the type of store search used for filtering results.
Not supported when CategoryID is specified in the request, and QueryKeywords is not included in the request.
See the Field Index to learn which calls use StoreSearch.

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

© 2006–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.