FindItemsAdvanced - Call Reference - eBay Shopping Web Services

FindItemsAdvanced

FindItemsAdvanced enables you to search for items on eBay based on many possible input fields and filters. Detailed information is returned about items.

The response to this call is in the form of an array whose size and contents you specify. You can filter the item listings returned using such criteria as the listing category and listing type.

On input, you specify keywords (including wildcards) or other criteria. Additionally, you can specify values to determine what item data is returned and how items are sorted.

You can choose how many items are returned in the response (for the maximum allowed, see MaxEntries). Based on the values in the TotalPages and TotalItems fields in the first call-response you receive, you can use the MaxEntries and PageNumber input fields to specify the item-sets returned in your second, third, etc. call-responses.

You can include or exclude sellers by specifying SellerID or SellerIDExclude; to use SellerID or SellerIDExclude, see Specifying Arrays in Requests.

For information about specifying the numeric value for the eBay site with the items you want information about, see Standard URL Parameters and HTTP Header Values. For information about specifying affiliate parameters, see Affiliate URL Parameters and HTTP Header Values.

FindItemsAdvanced requires that you specify at least one of the following fields: QueryKeywords, CategoryID, ProductID, or SellerID.

Using IncludeSelector Fields

The FindItemsAdvanced response contains a default set of data about items matching your request. If you want more data than the default data, you can use one or more IncludeSelector fields, as follows.

Details. Returns most available fields; includes ListingType and PaymentMethods.
SearchDetails. Returns additional fields that can affect the call's performance, e.g. DistanceFromBuyer, if available.
SellerInfo. Returns information about the seller; includes the user ID and feedback score of the seller
ItemSpecifics. Returns a list of attribute and value pairs. You also need to specify a query keyword when you set IncludeSelector to ItemSpecifics. If Condition is specified for the item condition or for a US eBay Motors vehicle, the list returns the item condition or the vehicle mileage and year. That is, the results only include attributes that would be included in the summary search results on the Web site (if any). In most categories, no summary attributes are returned in search results (even when the item is listed with Item Specifics.)
ExpansionItemCount. Returns the counts of items that would be returned with expansions.
CategoryHistogram. Returns a CategoryHistogram container with information about categories that match your search.

To use multiple IncludeSelector fields in a URL, separate them using a comma, for example: IncludeSelector=Details, SellerInfo

Using Search Criteria

FindItemsAdvanced enables you to use many criteria for searches, including the following. For more information, see the Input and Output sections below.

Item condition. Specify, for example, New in the Condition input field.
Number of bids. Specify, for example, BidCountMin to limit the results to items with a minimum number of bids.
Price range. You can use PriceMax or PriceMin, or both, to limit results based on the current price.
Criteria related to listing type. Use ItemType to specify criteria related to listing-type. For example, you must specify the AllItemTypes value in ItemType if you want Store Inventory format (StoresFixedPrice) items to be returned.
Time ending. Use EndTimeFrom and EndTimeTo to limit search results to items ending within a time range.

Searching by Product ID, Including ISBN

You can use the ProductID input field to search by ISBN, UPC, EAN, or eBay Product Reference ID. For example, to search using an eBay Product Reference ID (obtained with a FindProducts call), specify ProductID.Type=Reference and set ProductID.Value to an eBay Product Reference ID value.

Searching for Charity Listings, Items with Free Shipping, and Items with Other Features

You can use the SearchFlag input field to search for charity listings, items with free shipping, and other features.

Searching for Items that Have Changed

Use a ModTimeFrom value to limit the results to active items whose status has changed since the specified time. Specify a time in the past. Time must be in GMT; see ModTimeFrom and click the dateTime link for more information.

Searching by Category ID

Specify CategoryID to restrict your query to a specific category ID. When you include a CategoryID element in your request but you do not include a QueryKeyword value, you change the request mode to 'listing mode'. In listing mode, some elements will be available for you to use in a request that containts a CategoryID without a QueryKeyword, while other elements are not supported. When you make a FindItemsAdvanced call using CategoryID without a QueryKeyword, the other elements that you can use in your call are: ItemType, MaxDistance, PaymentMethod, PostalCode, PreferredLocation, PriceMax, PriceMin, EndTimeFrom,EndTimeTo, CharityID, FeedbackScoreMax, and FeedbackScoreMin. When using CategoryID in your call, you can only use the following sort options (and associated values): ItemSort with BestMatchCategoryGroup, BestMatch, Distance, PricePlusShipping, CurrentBid, BestMatchPlusEndTime, and BestMatchPlusPrice; SearchFlag with FreeShipping, GetItFast, and AutoPay; and Currency.

Sorting the Items Returned

Using values in the ItemSort and SortOrder input fields, you can specify one of many sort options. These options include BestMatch, BidCount, and others.

Retrieving BestMatch Results Grouped by Category

To retrieve BestMatch results grouped by category, specify a value of BestMatchCategoryGroup in the ItemSort field. BestMatch results are based on community buying activity and other relevance-based factors. Optionally, specify a value in GroupMaxEntries (maximum number of entries per group) and in GroupsMax (maximum number of groups).

Retrieving the Number of Items By Category

To retrieve the number of items by matching category, specify CategoryHistogram in the IncludeSelector field. If you want to specify a maximum number of matching categories at the highest category level (that is, at the level of Art, etc.), specify a value in the CategoryHistogramMaxParents field. If you want to specify a maximum number of matching categories at the subcategory level (that is, at the level below the level of Art, etc.), specify a value in the CategoryHistogramMaxChildren field.

Mapping GetSearchResults to FindItemsAdvanced

If you are familiar with the GetSearchResults call in the Trading API, please see the mapping of GetSearchResults to FindItemsAdvanced.

See:
Searching for Items by Using a Query for related information (applies primarily to the eBay Trading API)
Searching for Matching Categories for information about finding listings in categories (applies primarily to the eBay Trading API)

Related calls:

FindItems - Searches for items based on a query or a seller ID. If you use keywords, this call returns items that contain the keywords in the title. A maximum of 50 items is returned.
GetSingleItem - Gets publicly visible details about one listing. This gives you most of the data that eBay shows on the View Item page (title, description, price, and other details).

FindItemsAdvanced Input

The box below lists all fields that could be included in the call request. To learn more about an individual field or its type, click its name in the box (or scroll down to find it in the table below the box).

See also Samples.

See also the Deprecated Objects link above. Fields presented in this color are deprecated, and fields presented in this color are (or soon will be) non-operational.

<?xml version="1.0" encoding="utf-8"?>
<FindItemsAdvancedRequest xmlns="urn:ebay:apis:eBLBaseComponents">
  <!-- Standard Input Fields -->
  <MessageID> string </MessageID>
  <!-- Call-specific Input Fields -->
  <BidCountMax> int </BidCountMax>
  <BidCountMin> int </BidCountMin>
  <CategoryHistogramMaxChildren> int </CategoryHistogramMaxChildren>
  <CategoryHistogramMaxParents> int </CategoryHistogramMaxParents>
  <CategoryID> string </CategoryID>
  <CharityID> int </CharityID>
  <Condition> ItemConditionCodeType </Condition>
  <Currency> CurrencyCodeType </Currency>
  <DescriptionSearch> boolean </DescriptionSearch>
  <EndTimeFrom> dateTime </EndTimeFrom>
  <EndTimeTo> dateTime </EndTimeTo>
  <ExcludeFlag> ExcludeFlagCodeType </ExcludeFlag>
  <!-- ... more ExcludeFlag nodes here ... -->
  <FeedbackScoreMax> int </FeedbackScoreMax>
  <FeedbackScoreMin> int </FeedbackScoreMin>
  <GroupMaxEntries> int </GroupMaxEntries>
  <GroupsMax> int </GroupsMax>
  <IncludeSelector> string </IncludeSelector>
  <ItemsAvailableTo> CountryCodeType </ItemsAvailableTo>
  <ItemsLocatedIn> CountryCodeType </ItemsLocatedIn>
  <ItemSort> SimpleItemSortCodeType </ItemSort>
  <ItemType> ItemTypeCodeType </ItemType>
  <MaxDistance> int </MaxDistance>
  <MaxEntries> int </MaxEntries>
  <ModTimeFrom> dateTime </ModTimeFrom>
  <PageNumber> int </PageNumber>
  <PaymentMethod> PaymentMethodSearchCodeType </PaymentMethod>
  <PostalCode> string </PostalCode>
  <PreferredLocation> PreferredLocationCodeType </PreferredLocation>
  <PriceMax currencyID="CurrencyCodeType"> AmountType (double) </PriceMax>
  <PriceMin currencyID="CurrencyCodeType"> AmountType (double) </PriceMin>
  <ProductID type="ProductIDCodeType"> ProductIDType (string) </ProductID>
  <Quantity> int </Quantity>
  <QuantityOperator> QuantityOperatorCodeType </QuantityOperator>
  <QueryKeywords> string </QueryKeywords>
  <SearchFlag> SearchFlagCodeType </SearchFlag>
  <!-- ... more SearchFlag nodes here ... -->
  <SellerBusinessType> SellerBusinessCodeType </SellerBusinessType>
  <SellerID> string </SellerID>
  <!-- ... more SellerID nodes here ... -->
  <SellerIDExclude> string </SellerIDExclude>
  <!-- ... more SellerIDExclude nodes here ... -->
  <SortOrder> SortOrderCodeType </SortOrder>
  <StoreName> string </StoreName>
  <StoreSearch> StoreSearchCodeType </StoreSearch>
</FindItemsAdvancedRequest>

Argument	Type	Reqd?	Meaning
Standard Input Fields [Jump to call-specific fields]
MessageID	string	Optional	If you pass a value in MessageID in a request, we'll return the same value in CorrelationID in the response. If you're making a lot of calls, you can use this for tracking that a response is returned for every request and to match particular responses to particular requests. (In this case, specify a different value for each request.) You can specify any value that is useful to you.
Call-specific Input Fields
BidCountMax	int	Optional	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.
BidCountMin	int	Optional	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.
CategoryHistogramMaxChildren	int	Optional	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. Max: 10. Default: 3.
CategoryHistogramMaxParents	int	Optional	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. Max: 10. Default: 3.
CategoryID	string	Conditional	Specify CategoryID to restrict your query to a specific category. CategoryID cannot be used with the following input fields: EndTimeFrom, EndTimeTo, PriceMin, or PriceMax. 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. Max length: 10. See Searching by Category ID for related information (applies primarily to the eBay Trading API).
CharityID	int	Optional	Limits results to items that support the specified nonprofit charity organization.
Condition	ItemConditionCodeType	Optional	Limits the results to new or used items, 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). Applicable values: • CustomCode (in) Reserved for internal or future use. • New (in) The seller specified the Item Condition as New, or did not specify a condition. (Excludes items that the seller listed as Used.) • Used (in) The seller specified the Item Condition as Used, or did not specify a condition. (Excludes items that the seller listed as New.)
Currency	CurrencyCodeType	Optional	Limits the result set to just those items with a specified currency. Applicable values: See Currency.
DescriptionSearch	boolean	Optional	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.
EndTimeFrom	dateTime	Conditional	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.
EndTimeTo	dateTime	Conditional	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.
ExcludeFlag	ExcludeFlagCodeType (repeatable)	Optional	Excludes items with the specified flag from the search. Applicable values: • AutoPay (in) Exclude AutoPay item listings from the search results.
FeedbackScoreMax	int	Optional	Specifies the maximum feedback score of a seller whose items can be included in the response.
FeedbackScoreMin	int	Optional	Specifies the mininum feedback score of a seller whose items can be included in the response.
GroupMaxEntries	int	Optional	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.
GroupsMax	int	Optional	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.
IncludeSelector	string	Optional	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. • 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. See: Detail Controls FindItemsAdvanced Samples
ItemsAvailableTo	CountryCodeType	Optional	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. Applicable values: See ItemsAvailableTo.
ItemsLocatedIn	CountryCodeType	Optional	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. Applicable values: See ItemsLocatedIn.
ItemSort	SimpleItemSortCodeType	Optional	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.) Default: BestMatch. Applicable values: • BestMatch (in) Sorts items by Best Match, and no sort order applies. If specified, then Best Match sort also applies to CategoryHistogram. • BestMatchCategoryGroup (in) Sort by BestMatchCategoryGroup so results are grouped by Best Match within a category. • BestMatchPlusEndTime (in) Support Relevance (BestMatch) Filter as first pass and then sorts the result set by end time in ascending or descending order. • BestMatchPlusPrice (in) Support Relevance (BestMatch) Filter as first pass and then sorts the result set by Price in ascending or descending order. • BidCount (in) Sort by number of bids on the item in ascending or descending order. Not supported when CategoryID is specified in the FindItemsAdvanced request, and QueryKeywords is not included in the request. • Country (in) Sort by country; no sort order can be specified. Not supported when CategoryID is specified in the FindItemsAdvanced request, and QueryKeywords is not included in the request. • CurrentBid (in) Sort by current bid; descending order only. • CustomCode (in) Placeholder value. See token. • Distance (in) Sort by distance, ascending order only. • EndTime (in) Sorts items by end time. If you specify EndTime, then for SortOrder, you must specify a value of Ascending. The following is not functional: specifying a value of EndTime with a SortOrder of Descending. Not supported when CategoryID is specified in the FindItemsAdvanced request, and QueryKeywords is not included in the request. • PricePlusShipping (in) This value is part of the Price Plus Shipping Sort feature, available for the following sites: US (site ID 0), Germany (77), Canada (2), and Australia (15). The Price Plus Shipping Sort feature causes item sorting to consider shipping costs. Specify PricePlusShippingAsc to sort items by lowest cost first, as follows: Lowest-total-cost (for items where shipping was properly specified), then freight-shipping items, then items for which shipping was not specified (sorted by price). • StartDate (in) Sort by start date, recently-listed first. Not supported when CategoryID is specified in the FindItemsAdvanced request, and QueryKeywords is not included in the request.
ItemType	ItemTypeCodeType	Optional	Filters items based on criteria related to the listing type of items. Applicable values: • AdFormat (in) Restricts listings to return only items that have the Ad Format feature. • AllFixedPriceItemTypes (in) Retrieves fixed-price items. Whether StoresFixedPrice items are retrieved does not depend on the site default. The StoresFixedPrice items are retrieved after the basic fixed price items. Items are retrieved whether or not listing type is set to StoresFixedPrice. Does not retrieve items for which listing type is AdType or Live. Does not retrieve auction items for which BuyItNowEnabled is false. • AllItems (in) Returns all listing types (the default for FindItemsAdvanced). It is recommended that you use AllItemTypes instead of AllItems. Whether StoresFixedPrice items are retrieved depends on the site default. • AllItemTypes (in) Retrieves listings whether or not listing type is set to StoresFixedPrice; include auction items. In searches for items, you must specify the AllItemTypes value if you want Store Inventory format (StoresFixedPrice) items to be returned. • AuctionItemsOnly (in) Only retrieve listings eligible for competitive bidding at auction. That is, only retrieve listings for which ListingType is Chinese, Dutch, or Live (regardless of the BuyItNowEnabled value). If a listing has a listing type of any of the following, it is not retrieved: StoresFixedPrice, FixedPriceItem, and AdType. • ClassifiedItemsOnly (in) Only retrieves Classified Ad format listings. • CustomCode (in) Reserved for internal or future use. • ExcludeStoreInventory (in) Excludes listings that have listing type set to StoresFixedPrice. • FixedPricedItem (in) Only retrieves listings that can be purchased at a fixed price. That is, only retrieves listings for which listing type is StoresFixedPrice or FixedPriceItem. Whether StoresFixedPrice items are retrieved depends on the site default. If StoresFixedPrice items are retrieved, they are returned after the other retrieved items. Also retrieves Chinese and Dutch auction listings for which BuyItNowEnabled is true. Does not retrieve listings for which listing type is AdType or Live, and does not retrieve auction listings for which BuyItNowEnabled is false. • FixedPriceExcludeStoreInventory (in) Excludes listings that have listing type set to StoresFixedPrice. Excludes listings that have listing type set to AdType or Live. Excludes auction listings in which BuyItNowEnabled is false. • StoreInventoryOnly (in) Only retrieves listings for which the listing type is StoresFixedPrice.
MaxDistance	int	Optional	The maximum distance from the item-location value you specify in PostalCode. 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.
MaxEntries	int	Optional	Specifies the maximum number of entries to return 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. Max: 100. Default: 20.
ModTimeFrom	dateTime	Optional	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.
PageNumber	int	Optional	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). Default: 1.
PaymentMethod	PaymentMethodSearchCodeType	Optional	Limits results to items that accept a specific payment method or methods. Applicable values: • CustomCode (in) Reserved for internal or future use. • PaisaPay (in) PaisaPay payment method. The PaisaPay payment method is only for the India site (site ID 203). • PaisaPayEscrowEMI (in) PaisaPayEscrow EMI (Equal Monthly Installment) payment method. The PaisaPayEscrowEMI payment method is only for the India site (site ID 203). • PayPal (in) PayPal payment method. • PayPalOrPaisaPay (in) Either the PayPal or the PaisaPay payment method. The PaisaPay payment method is only for the India site (site ID 203).
PostalCode	string	Optional	The postal code where an item is located. The search behavior depends on the combination of MaxDistance and Postal Code values. See MaxDistance element for details.
PreferredLocation	PreferredLocationCodeType	Optional	Specifies the criteria for filtering search results by site, where site is determined by the site ID in the request. Applicable values: • AvailableInCountryImplied (in) Items available to the country implied by the site specified in the request. For the US site, this implies listings from ALL English-language countries that are available to the US. • BelgiumListing (in) Items located in Belgium or listed on one of the two Belgian sites. • CustomCode (in) Reserved for internal or future use. • ListedInCurrencyImplied (in) Items listed in the currency implied by the site specified in the request. • LocatedInCountryImplied (in) Items located in the country implied by the site specified in the request. • SiteImplied (in) Items listed on the site specified in the request, regardless of listing currency.
PriceMax	AmountType (double)	Optional	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.
PriceMax [ attribute currencyID ]	CurrencyCodeType	Optional	Currency in which the monetary amount is specified. See CurrencyCodeType for applicable values. For a list of possible enumeration values, see CurrencyCodeType.
PriceMin	AmountType (double)	Optional	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.
PriceMin [ attribute currencyID ]	CurrencyCodeType	Optional	Currency in which the monetary amount is specified. See CurrencyCodeType for applicable values. For a list of possible enumeration values, see CurrencyCodeType.
ProductID	ProductIDType (string)	Optional	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.
ProductID [ attribute type ]	ProductIDCodeType	Conditional	The nature of identifier being used. For FindHalfProducts, FindProducts, FindItemsAdvanced, and FindReviewsAndGuides, only Reference, ISBN, UPC, and EAN are supported. Required when ProductID is specified. For a list of possible enumeration values, see ProductIDCodeType.
Quantity	int	Optional	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.
QuantityOperator	QuantityOperatorCodeType	Optional	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. Applicable values: • CustomCode (in) Reserved for internal or future use. • Equal (in) Specifies quantities equal to Quantity. • GreaterThan (in) Specifies quantities greater than Quantity. • GreaterThanOrEqual (in) Specifies quantities greater than or equal to Quantity. • LessThan (in) Used by QuantityOperator to specify that you are seeking quantities less than Quantity. • LessThanOrEqual (in) Specifies quantities less than or equal to Quantity.
QueryKeywords	string	Conditional	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. Max length: 350 (characters). See: Searching by Keywords for related information (applies primarily to the eBay Trading API) string
SearchFlag	SearchFlagCodeType (repeatable)	Optional	Search for charity listings, free-shipping listings, and listings with other features. Applicable values: • AutoPay (in) Return only AutoPay item listings. • Charity (in) Return only charity item listings. Not supported when CategoryID is specified in the request, and QueryKeywords is not included in the request. • CustomCode (in) Reserved for internal or future use. • Featured (in) Return only featured item listings. Not supported when CategoryID is specified in the request, and QueryKeywords is not included in the request. • FreeShipping (in) If specified, 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. • Gallery (in) Return Gallery items only. Not supported when CategoryID is specified in the request, and QueryKeywords is not included in the request. • GermanMotorsSearchable (in) Limits the results based on each item's eligibility to appear on the mobile.de site. If specified, 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. Not supported when CategoryID is specified in the request, and QueryKeywords is not included in the request. • GetItFast (in) Limits the results to Get It Fast listings. • Gift (in) Return only gift items. Not supported when CategoryID is specified in the request, and QueryKeywords is not included in the request. • LocalSearch (in) Perform a local search. Not supported when CategoryID is specified in the request, and QueryKeywords is not included in the request. • Lot (in) Limits the results to only those listings for which lot size is 2 or greater. Not supported when CategoryID is specified in the request, and QueryKeywords is not included in the request. • NowAndNew (in) Return only items that have been listed with Now and New. Applicable for certain sites only. Not supported when CategoryID is specified in the request, and QueryKeywords is not included in the request. • Picture (in) Picture. Not supported when CategoryID is specified in the request, and QueryKeywords is not included in the request. • SuperFeatured (in) Return only super-featured item listings. Not supported when CategoryID is specified in the request, and QueryKeywords is not included in the request. (Not all values in SearchFlagCodeType apply to this field.)
SellerBusinessType	SellerBusinessCodeType	Optional	Limits the results to those of a particular seller business type such as commercial or private. SellerBusinessType 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. Applicable values: • Commercial (in/out) Commercial seller account. • CustomCode (in/out) Reserved for internal or future use. • Private (in/out) Private seller account. • Undefined (in/out) Type of seller account not defined.
SellerID	string (repeatable)	Optional	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.
SellerIDExclude	string (repeatable)	Optional	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.
SortOrder	SortOrderCodeType	Optional	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. Default: Descending. Applicable values: • Ascending (in) Sorts results in ascending (low to high) order. • CustomCode (in) Placeholder value. See token. • Descending (in) Sorts results in descending (high to low) order.
StoreName	string	Optional	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.
StoreSearch	StoreSearchCodeType	Optional	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. Applicable values: • AllItemsInTheStore (in) Within a single store for all items (specify a store in the appropriate input field). • AuctionItemsInTheStore (in) Within a single store for auction items (specify a store in the appropriate input field). • BuyItNowItemsInAllStores (in) Across all stores for basic fixed price items, Store Inventory format items, and auction items with Buy It Now. • BuyItNowItemsInTheStore (in) Within a single store for basic fixed price items, Store Inventory format items, and auction items with Buy It Now (specify a store in the appropriate input field). • CustomCode (in) Reserved for internal or future use.

FindItemsAdvanced Output

The box below lists all fields that might be returned in the call response. To learn more about an individual field or its type, click its name in the box (or scroll down to find it in the table below the box).