FindItems - Call Reference - eBay Shopping Web Services

FindItems

Searches for items based a query or seller ID. If you use keywords, this call returns items that contain the keywords in the title.

A maximum of 50 items is returned. However, you can use the value returned in the ItemSearchURL field to enable users to view more than 50 items. Store Inventory format (StoresFixedPrice) items are not returned by this call.

On input, you specify keywords or seller IDs. Additionally, you can specify values for sorting the items returned based on Best Match or end time. You also can specify a buyer's postal code and you can exclude seller IDs.

For example, you can search for listings containing "Toy" and also specify that items returned are sorted by Best Match.

For a tutorial about using this call, see Getting Started with Search in the eBay Shopping API: Specifying JSON Results.

If you want to specify a seller ID, see the sample below and 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.

Related calls:

FindItemsAdvanced - Searches for items based on many possible input fields. Detailed information is returned about items.
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).
GetItemStatus - Allows you to get the status for a group of items. Returns status information such as ListingStatus and End Time for all items that are listed in the request. Duplicated items are returned as a single item.
GetShippingCosts - Gets shipping costs for an item.

FindItems 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).

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
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. • 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. (Not all values in SimpleItemSortCodeType apply to this field.)
MaxEntries	int	Optional	Specifies the maximum number of entries to return in a single call. If the number of entries that can be returned is less than the value you specify, the lower number is returned. Max: 50. Default: 3.
PostalCode	string	Optional	Specifies the postal code where the buyer is located.
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. FindItems requires that you specify either QueryKeywords, SellerID, or both. Max length: 350 (characters). See string.
SellerID	string (repeatable)	Conditional	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. The value you specify in SellerID is ignored if it is invalid. You can specify a maximum of 100 sellers.
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.
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, in the case of the (default) ItemSort value of BestMatch, the most relevant items are returned first, because the default SortOrder value is Descending. If you specify an ItemSort value of EndTime (to sort items by end time), and a SortOrder value of Ascending, then items ending in less time (from the time of the call) are returned before items ending in more time. 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.

See also Samples.

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

<?xml version="1.0" encoding="utf-8"?>
<FindItemsResponse xmlns="urn:ebay:apis:eBLBaseComponents">
  <!-- Standard Output Fields -->
  <Ack> AckCodeType </Ack>
  <Build> string </Build>
  <CorrelationID> string </CorrelationID>
  <Errors> ErrorType 
    <ErrorClassification> ErrorClassificationCodeType </ErrorClassification>
    <ErrorCode> token </ErrorCode>
    <ErrorParameters ParamID="string"> ErrorParameterType 
      <Value> string </Value>
    </ErrorParameters>
    <!-- ... more ErrorParameters nodes here ... -->
    <LongMessage> string </LongMessage>
    <SeverityCode> SeverityCodeType </SeverityCode>
    <ShortMessage> string </ShortMessage>
  </Errors>
  <!-- ... more Errors nodes here ... -->
  <Timestamp> dateTime </Timestamp>
  <Version> string </Version>
  <!-- Call-specific Output Fields -->
  <Item> SimpleItemType 
    <BidCount> int </BidCount>
    <BuyItNowAvailable> boolean </BuyItNowAvailable>
    <ConvertedBuyItNowPrice currencyID="CurrencyCodeType"> AmountType (double) </ConvertedBuyItNowPrice>
    <ConvertedCurrentPrice currencyID="CurrencyCodeType"> AmountType (double) </ConvertedCurrentPrice>
    <EndTime> dateTime </EndTime>
    <GalleryURL> anyURI </GalleryURL>
    <ItemID> string </ItemID>
    <ListingStatus> ListingStatusCodeType </ListingStatus>
    <ListingType> ListingTypeCodeType </ListingType>
    <PrimaryCategoryID> string </PrimaryCategoryID>
    <PrimaryCategoryName> string </PrimaryCategoryName>
    <ShippingCostSummary> ShippingCostSummaryType 
      <ShippingServiceCost currencyID="CurrencyCodeType"> AmountType (double) </ShippingServiceCost>
      <ShippingType> ShippingTypeCodeType </ShippingType>
    </ShippingCostSummary>
    <TimeLeft> duration </TimeLeft>
    <Title> string </Title>
    <ViewItemURLForNaturalSearch> anyURI </ViewItemURLForNaturalSearch>
  </Item>
  <!-- ... more Item nodes here ... -->
  <ItemSearchURL> anyURI </ItemSearchURL>
  <TotalItems> int </TotalItems>
</FindItemsResponse>

Return Value	Type	Returned?	Meaning
Standard Output Fields [Jump to call-specific fields]
Ack	AckCodeType	Always	Indicates whether the call was successfully processed by eBay. Applicable values: • CustomCode (out) Reserved for internal or future use. • Failure (out) Request processing failed • Success (out) Request processing succeeded • Warning (out) Request processing completed with warning information being included in the response message (Not all values in AckCodeType apply to this field.)
Build	string	Always	This refers to the particular software build that eBay used when processing the request and generating the response. This includes the version number plus additional information. eBay Developer Support may request the build information when helping you resolve technical issues.
CorrelationID	string	Conditionally	If you pass a value in MessageID in a request, we will return the same value in CorrelationID in the response. You can use this for tracking that a response is returned for every request and to match particular responses to particular requests. Only returned if MessageID was used.
Errors	ErrorType (repeatable)	Conditionally	A list of application-level errors or warnings (if any) that were raised when eBay processed the request. Application-level errors occur due to problems with business-level data on the client side or on the eBay server side. For example, an error would occur if the request contains an invalid combination of fields, or it is missing a required field, or the value of the field is not recognized. An error could also occur if eBay encountered a problem in our internal business logic while processing the request. Only returned if there were warnings or errors.
Errors.ErrorClassification	ErrorClassificationCodeType	Conditionally	API errors are divided between two classes: system errors and request errors. Applicable values: • CustomCode (out) Reserved for internal or future use. • RequestError (out) An error has occurred either as a result of a problem in the sending application or because the application's end-user has attempted to submit invalid data (or missing data). In these cases, do not retry the request. The problem must be corrected before the request can be made again. If the problem is due to something in the application (such as a missing required field), the application must be changed. If the problem is a result of end-user data, the application must alert the end-user to the problem and provide the means for the end-user to correct the data. Once the problem in the application or data is resolved, resend the request to eBay with the corrected data. • SystemError (out) Indicates that an error has occurred on the eBay system side, such as a database or server down. An application can retry the request as-is a reasonable number of times (eBay recommends twice). If the error persists, contact Developer Technical Support. Once the problem has been resolved, the request may be resent in its original form. See Errors by Number.
Errors.ErrorCode	token	Conditionally	A unique code that identifies the particular error condition that occurred. Your application can use error codes as identifiers in your customized error-handling algorithms. See Errors by Number.
Errors.ErrorParameters	ErrorParameterType (repeatable)	Conditionally	Some warning and error messages return one or more variables that contain contextual information about the error. This is often the field or value that triggered the error. You can usually predict where these will occur by looking at the "replaceable_value" indicators in our Errors by Number page. See Errors by Number.
Errors.ErrorParameters [ attribute ParamID ]	string	Conditionally	The index of the parameter in the error.
Errors.ErrorParameters.Value	string	Conditionally	The value of the variable.
Errors.LongMessage	string	Conditionally	A more detailed description of the condition that raised the error. See Errors by Number.
Errors.SeverityCode	SeverityCodeType	Conditionally	Indicates whether the error caused the request to fail. If the request fails and the source of the problem is within the application (such as a missing required element), please change the application before you retry the request. If the problem is due to end-user input data, please alert the end-user to the problem and provide the means for them to correct the data. Once the problem in the application or data is resolved, you can attempt to re-send the request to eBay. If the source of the problem is on eBay's side, you can retry the request as-is a reasonable number of times (eBay recommends twice). If the error persists, contact Developer Technical Support. Once the problem has been resolved, the request may be resent in its original form. When a warning occurs, the error is returned in addition to the business data. In this case, you do not need to retry the request (as the original request was successful). However, depending on the cause or nature of the warning, you might need to contact either the end user or eBay to effect a long term solution to the problem to prevent it from reoccurring in the future. Applicable values: • CustomCode (out) Reserved for internal or future use • Error (out) The request that triggered the error was not processed successfully. When a serious application-level error occurs, the error is returned instead of the business data. • Warning (out) The request was processed successfully, but something occurred that may affect your application or the user. For example, eBay may have changed a value the user sent in. In this case, eBay returns a normal, successful response and also returns the warning. See: Errors by Number Requirements for Error Handling for more information (in the eBay Trading Web Services guide)
Errors.ShortMessage	string	Conditionally	A brief description of the condition that raised the error. See Errors by Number.
Timestamp	dateTime	Always	This value represents the date and time when eBay processed the request. The time zone of this value is GMT and the format is the ISO 8601 date and time format (YYYY-MM-DDTHH:MM:SS.SSSZ). See the "dateTime" type for information about this time format and converting to and from the GMT time zone.
Version	string	Always	The release version that eBay used to process the request. Note: This is usually the latest release version, as specified in the release notes. (eBay releases the API to international sites about a week after we release it to the US site.) If a field in the response returns the token "CustomCode", it usually means that the field is a code type (a token or enumeration), and that in your request URL (or HTTP header) you specified a version that is older than the version in which the token was added to the call. See eBay Versioning Strategy.
Call-specific Output Fields
Item	SimpleItemType (repeatable)	Conditionally	Contains summary data for an item listing.
Item.BidCount	int	Conditionally	The number of bids that have been placed on the item. On most sites, once a Chinese auction has bids, the listing is no longer eligible for Buy It Now. (This is not necessarily true for Dutch auctions. See Item.BuyItNowAvailable for Dutch auctions.)
Item.BuyItNowAvailable	boolean	Conditionally	For Dutch auctions (not Chinese auctions) this indicates whether there is a Buy It Now option. (On some sites, the Buy It Now option remains available for Dutch auctions even after there are bids.) Applicable to the Germany site (site ID 77) only.
Item.ConvertedBuyItNowPrice	AmountType (double)	Conditionally	The listing's Buy It Now Price (if any), converted into the currency of the site to which you sent this request. Price fields are returned as doubles, not necessarily in the traditional monetary format of the site's country. For example, a US Dollar value might be returned as 3.880001 instead of 3.88. For Chinese auctions (Quantity=1, competitive bidding online auctions), Buy It Now lets a user purchase the item at a fixed price and end the auction immediately. On most sites, after a Chinese auction has bids, the listing is no longer eligible for Buy It Now. However, calls like FindItems still return the Buy It Now Price that the seller set for the listing. Use the Item.BidCount field to determine whether an auction with Buy It Now has bids or not (and therefore whether it is still eligible to be purchased with Buy It Now). Some eBay sites also support Buy It Now for Dutch auctions (multi-quantity, competitive bidding), where you can buy multiple items from the same listing at a fixed price, instead of bidding. On some sites, the Buy It Now option remains available for Dutch auctions even after there are bids. See Item.BuyItNowAvailable. For fixed-price (FixedPriceItem) and Store Inventory listings (StoresFixedPrice), see CurrentPrice or ConvertedCurrentPrice instead. Only returned if an item was listed with Buy It Now. For active items, refresh this value every 24 hours to pick up the current conversion rates (if this value has been converted). See: (GetSingleItem) Item.ListingType Item.BuyItNowAvailable Item.BuyItNowPrice Item.ConvertedCurrentPrice (eBay Help) Buying with Buy It Now (eBay DE Hilfe) Kaufen mit Sofort-Kaufen
Item.ConvertedBuyItNowPrice [ attribute currencyID ]	CurrencyCodeType	Conditionally	Currency in which the monetary amount is specified. See CurrencyCodeType for applicable values. For a list of possible enumeration values, see CurrencyCodeType.
Item.ConvertedCurrentPrice	AmountType (double)	Conditionally	The listing's current price, converted to the currency of the site specified in the request. If the item is a multi-quantity listing, this is the price of one item. Price fields are returned as doubles, not necessarily in the usual monetary amount format of the site. For example, a US Dollar value might be returned as 3.879938 instead of 3.88. For competitive-bidding listings (Chinese and Dutch auctions), this is the current minimum bid price (if the listing has no bids) or the current high bid (if the listing has bids). (Compare to BuyItNowPrice). For Basic Fixed-Price (FixedPriceItem), Store Inventory (StoresFixedPrice), and Ad format (AdType) listings, this is the current fixed price. For active items, refresh this value every 24 hours to pick up the current conversion rates (if this value has been converted).
Item.ConvertedCurrentPrice [ attribute currencyID ]	CurrencyCodeType	Conditionally	Currency in which the monetary amount is specified. See CurrencyCodeType for applicable values. For a list of possible enumeration values, see CurrencyCodeType.
Item.EndTime	dateTime	Conditionally	Time stamp (in GMT) of when the listing is scheduled to end, or time stamp of the actual end time (if the item ended). In FindItemsAdvanced and FindItems, for StoresFixedPrice items which are "Good Till Canceled," this value is 5 minutes later than the actual end time of the item. The discrepancy is intended to facilitate renewal every 30 days of such items' end times.
Item.GalleryURL	anyURI	Conditionally	URL for a picture used as the Gallery thumbnail, if any. The image uses one of the following graphics formats: JPEG, BMP, TIF, or GIF. Only returned if the seller chose to show a gallery image.
Item.ItemID	string	Conditionally	The ID that uniquely identifies the item listing. eBay generates this ID when an item is listed. This ID is unique across all eBay sites. Max length: 19 (Note: The eBay database specifies 38. Currently, Item IDs are usually 9 to 12 digits).
Item.ListingStatus	ListingStatusCodeType	Conditionally	Specifies a listing's status in eBay's processing workflow. If an item's EndTime is in the past, but no details about the buyer or high bidder are shown (and the user is not anonymous), use this listing status information to determine whether eBay has finished processing the listing. Applicable values: • Active (out) The listing is still live, or it has recently ended but eBay has not completed processing the listing (e.g., we're still determining the high bidder). A multi-item listing is considered active until all items have winning bids or purchases or the listing's end time has passed. (That is, if the listing has a Quantity of 10, the sale of 1 of those items doesn't end the listing.) If the listing has ended but this Active status is returned, please allow several minutes for eBay to finish processing the listing. • Completed (out) The listing has ended and eBay has completed processing of the sale (if any), such as determining the high bidder. You can think of Completed and Ended as essentially equivalent. (The difference is only meaningful to the seller of the item, as Completed indicates whether eBay has finished calculating certain selling fees.) • CustomCode (out) Placeholder value. See token. • Ended (out) The listing has ended and eBay has completed processing of the sale (if any), such as determining the high bidder.
Item.ListingType	ListingTypeCodeType	Conditionally	The format of the listing, such as online auction, fixed price, or advertisement format. Applicable values: • AdType (out) Advertisement to solicit inquiries on listings such as real estate. Permits no bidding on that item, service, or property. To express interest, a buyer fills out a contact form that eBay forwards to the the seller as a lead. This format does not enable buyers and sellers to transact online through eBay, and eBay Feedback is not available for ad format listings. • Auction (out) Reserved for future use. • Chinese (out) Single-quantity online auction format. A Chinese auction has a Quantity of 1. Buyers engage in competitive bidding, although Buy It Now may be offered as long as no bids have been placed. Online auctions are listed on eBay.com, and they are also listed in the seller's eBay Store if the seller is a Store owner. • CustomCode (out) Placeholder value. See token. • Dutch (out) Multiple-quantity online auction format. A Dutch auction has a Quantity greater than 1. Buyers engage in competitive bidding. Some sites also offer Buy It Now for Dutch auctions. Online auctions are listed on eBay.com, and they are also listed in the seller's eBay Store if the seller is a Store owner. • Express (out) For Germany only: eBay Express-only format (item is listed only on eBay Express Germany, not on eBay). • FixedPriceItem (out) A basic fixed-price listing with a Quantity of 1 or more. Allows no auction-style bidding. Also known as Buy It Now Only on some sites (not to be confused with the BuyItNow option that is available for Chinese auctions). Fixed-price listings appear on eBay.com, and they are also listed in the seller's eBay Store if the seller is a Store owner. • Half (out) Half.com listing (item is listed on Half.com, not on eBay). Reserved for future use. • LeadGeneration (out) Lead Generation format (advertisement-style listing to solicit inquiries or offers, no bidding or fixed price, listed on eBay). • Live (out) Live auction, on-site auction that can include non-eBay bidders. Live auctions are listed on the eBay Live Auctions site, in live auction categories. They can also appear on eBay if the seller lists the lot in a secondary category that is an eBay category. • PersonalOffer (out) Second chance offer made to a non-winning bidder on an ended listing. A seller can make an offer to a non-winning bidder when either the winning bidder has failed to pay for an item or the seller has a duplicate of the item. Second-chance offer items are on eBay, but they do not appear when browsing or searching listings. You need to already know the item ID in order to retrieve a second-chance offer. • StoresFixedPrice (out) A fixed-price format for eBay Store sellers. Store Inventory listings appear after other listings in regular browse and search item lists on eBay. They have a lower Insertion Fee and longer listing durations. Only specified by sellers who have an eBay Store. Store Inventory listings are listed on eBay.com, and they are also listed in the seller's eBay Store. • Unknown (out) Unknown auction type. (This is not normally used.)
Item.PrimaryCategoryID	string	Conditionally	Numeric ID of the first (or only) category in which the item is listed. (Listings can appear in more than one category.) Note: Currently, GetSingleItem does not return a listing's secondary category, if any.
Item.PrimaryCategoryName	string	Conditionally	Display name of the first (or only) category in which the item is listed. This is a fully qualified category breadcrumb (e.g., Computers & Networking:Laptops, Notebooks).
Item.ShippingCostSummary	ShippingCostSummaryType	Conditionally	Contains basic shipping-related costs for the item. If Item.Quantity is greater than 1, this is the shipping cost for one item. If the seller offers a choice of more than one shipping service (such as UPS Ground and USPS Media mail), this is the cost of the "first" shipping option (usually the lowest cost option). If a listing has shipping costs, use GetShippingCosts if you want to get more details about the services and costs that the seller is offering. See GetShippingCosts.
Item.ShippingCostSummary .ShippingServiceCost	AmountType (double)	Conditionally	The basic shipping cost of the item. If multiple items were purchased, this includes the ShippingServiceAdditionalCost.
Item.ShippingCostSummary .ShippingServiceCost [ attribute currencyID ]	CurrencyCodeType	Conditionally	Currency in which the monetary amount is specified. See CurrencyCodeType for applicable values. For a list of possible enumeration values, see CurrencyCodeType.
Item.ShippingCostSummary .ShippingType	ShippingTypeCodeType	Conditionally	How the seller stated that cost of shipping is to be determined, such as flat rate or calculated or free. In GetSingleItem, this is always returned when ShippingCostSummary is returned. Applicable values: • Calculated (out) The calculated shipping model: the posted cost of shipping is based on the seller-offered and buyer-selected shipping service, where the shipping costs are calculated by eBay and the shipping carrier based on the buyer's address, and any packaging/handling costs established by the seller are automatically rolled into the total. • CalculatedDomesticFlatInternational (out) The seller specified one or more calculated domestic shipping services and one or more flat international shipping services. • CustomCode (out) Placeholder value. See token. • Flat (out) The flat rate shipping model: the seller establishes the cost of shipping and cost of shipping insurance, regardless of what any buyer-selected shipping service might charge the seller. • FlatDomesticCalculatedInternational (out) The seller specified one or more flat domestic shipping services and one or more calculated international shipping services. • Free (out) Free is used when the seller is declaring that shipping is free for the buyer. Since Free cannot be selected via API, the seller has two options for signifying that shipping is free when listing an item: - omit shipping details, mention in the item description that shipping is free, and set ShippingTermsInDescription to true - select an arbitrary shipping service and set its shipping cost to 0, mention in the item description that shipping is free, and set ShippingTermsInDescription to true The latter is a better way to communicate "free shipping" because eBay picks up the "0" cost and can more accurately identify shipping costs in search results. • Freight (out) The freight shipping model: the cost of shipping is determined by a third party, FreightQuote.com, based on the item location (zip code). Currently, Freight can only be specified on input via eBay Web site, not via API. • NotSpecified (out) The seller did not specify the shipping type.
Item.TimeLeft	duration	Conditionally	Time left before the listing ends. The duration is represented in the ISO 8601 duration format (PnYnMnDTnHnMnS). For ended listings, the time left is PT0S (zero seconds).
Item.Title	string	Conditionally	Name of the item as it appears in the listing or in search and browse results. For US eBay Motors cars, trucks, and motorcycles, this value shows the vehicle Make and Model instead of the seller's own title. (For the seller's title, look for Subtitle in Item.ItemSpecifics.NameValueList.Name in GetSingleItem, and then use the corresponding value in Item.ItemSpecifics.NameValueList.Value.)
Item .ViewItemURLForNaturalSearch	anyURI	Conditionally	The URL to view this listing on eBay. This URL is optimized to support natural search. That is, this URL is designed to make items on eBay easier to find via popular Internet search engines. For example, this URL specifies the item title, and it is optimized for natural search: "_W0QQ" is like "?" (question mark), "QQ" is like "&" (ampersand), and "Z" is like "=" (equals sign). You shouldn't modify the query syntax in your application. For example, eBay won't recognize the URL if you change QQ to ?. In the Sandbox environment and on the Hong Kong site (site ID 201), the data returned in this field by FindItemsAdvanced is a standard ViewItem URL, rather than the ViewItem URL for natural search that generally is returned in the Production environment.
ItemSearchURL	anyURI	Conditionally	A URL equivalent to your FindItems search query. FindItems returns a maximum of 50 items, so you can use the value in ItemSearchURL to provide users with a link for viewing more items.
TotalItems	int	Always	Indicates the total number of items on eBay that match the query.

FindItems Detail Controls

This call does not use a detail control mechanism.

FindItems Samples

New to making API calls? Please see Making an API Call.

Note: Some item IDs, user IDs, or other data in these samples might no longer be active on eBay. If necessary, you can substitute current eBay data in your requests.

Available samples:

Basic Call ↓ - This is a basic search for items. For a tutorial that uses this call, see Getting Started with Search in the eBay Shopping API: Specifying JSON Results.
Specifying SellerID Values Call ↓ - This sample shows how to specify two SellerID values and a maximum number of entries to be returned. This sample searches for items listed by the specified sellers.
Basic Call with Affiliate Tracking ↓ - This is a basic search for items that would enable you to get commissions using affiliate tracking functionality.

Sample: Basic Call

This is a basic search for items. For a tutorial that uses this call, see Getting Started with Search in the eBay Shopping API: Specifying JSON Results.

Input

Here are 2 ways to make a request that searches item titles for words you specify. In both cases you must specify standard values.

URL format (HTTP GET). See also the non-wrapped version of this URL. For results in a format other than XML, 
specify a different value for responseencoding.

http://open.api.ebay.com/shopping?callname=FindItems
   &responseencoding=XML
   &appid=YourAppIDHere
   &siteid=0
   &version=517
   &QueryKeywords=harry%20potter%20phoenix
   &MaxEntries=50

Here is the same input in XML format (HTTP POST). Note that this does not include standard values.

XML format (HTTP POST). Also available are the .txt version of this XML and the SOAPSOAP and SOAP equivalents.

<?xml version="1.0" encoding="utf-8"?>
<FindItemsRequest xmlns="urn:ebay:apis:eBLBaseComponents">
  <QueryKeywords>harry potter phoenix</QueryKeywords>
  <MaxEntries>50</MaxEntries>
</FindItemsRequest>

Output

If you chose XML as the response encoding type, you would get something like this.

XML format. Also available are the .txt version of this XML and the SOAP, JSON and NV equivalents.

  <?xml version="1.0" encoding="UTF-8" ?> 
  <FindItemsResponse xmlns="urn:ebay:apis:eBLBaseComponents">
    <Timestamp>2007-06-07T02:24:11.437Z</Timestamp> 
    <Ack>Success</Ack> 
    <Build>e515_core_APILW_4756831_R1</Build> 
    <Version>515</Version> 
      <Item>
      <ItemID>180126682091</ItemID> 
      <ConvertedBuyItNowPrice currencyID="USD">0.0</ConvertedBuyItNowPrice> 
      <EndTime>2007-06-12T18:51:06.000Z</EndTime> 
      <ViewItemURLForNaturalSearch>http://cgi.ebay.com/EMMA-WATSON-entertainment-weekly-HARRY-POTTER-phoenix_W0QQitemZ180126682091QQcategoryZ29798QQcmdZViewItem</ViewItemURLForNaturalSearch> 
      <GalleryURL>http://thumbs.ebaystatic.com/pict/180126682091.jpg</GalleryURL> 
      <PrimaryCategoryID>29798</PrimaryCategoryID> 
      <PrimaryCategoryName>Collectibles:Fantasy, Mythical & Magic:Harry Potter:Other Items</PrimaryCategoryName> 
      <BidCount>0</BidCount> 
      <ConvertedCurrentPrice currencyID="USD">0.88</ConvertedCurrentPrice> 
      <ListingStatus>Active</ListingStatus> 
      <TimeLeft>P5DT16H26M55S</TimeLeft> 
      <Title>EMMA WATSON entertainment weekly HARRY POTTER phoenix</Title> 
      <ShippingCostSummary>
        <ShippingServiceCost currencyID="USD">4.75</ShippingServiceCost> 
        <ShippingType>Flat</ShippingType> 
      </ShippingCostSummary>
    </Item>
    <Item>
      <ItemID>140126038381</ItemID> 
      <ConvertedBuyItNowPrice currencyID="USD">0.0</ConvertedBuyItNowPrice> 
      <EndTime>2007-06-09T02:33:26.000Z</EndTime> 
      <ViewItemURLForNaturalSearch>http://cgi.ebay.com/HARRY-POTTER-PHOENIX-MOVIE-COOL-9-WALL-CLOCK-NEW_W0QQitemZ140126038381QQcategoryZ2312QQcmdZViewItem</ViewItemURLForNaturalSearch> 
      <PrimaryCategoryID>2312</PrimaryCategoryID> 
      <PrimaryCategoryName>Entertainment Memorabilia:Other Memorabilia</PrimaryCategoryName> 
      <BidCount>0</BidCount> 
      <ConvertedCurrentPrice currencyID="USD">15.99</ConvertedCurrentPrice> 
      <ListingStatus>Active</ListingStatus> 
      <TimeLeft>P2DT9M15S</TimeLeft> 
      <Title>HARRY POTTER PHOENIX MOVIE COOL 9" WALL CLOCK NEW</Title> 
      <ShippingCostSummary>
        <ShippingServiceCost currencyID="USD">7.01</ShippingServiceCost> 
        <ShippingType>Flat</ShippingType> 
      </ShippingCostSummary>
    </Item>
    <Item>
      <ItemID>300118132027</ItemID> 
      <ConvertedBuyItNowPrice currencyID="USD">0.0</ConvertedBuyItNowPrice> 
      <EndTime>2007-06-07T16:52:09.000Z</EndTime> 
      <ViewItemURLForNaturalSearch>http://cgi.ebay.com/Gentle-Giant-Harry-Potter-Phoenix-Year-5-Harry-Bust_W0QQitemZ300118132027QQcategoryZ88895QQcmdZViewItem</ViewItemURLForNaturalSearch> 
      <GalleryURL>http://thumbs.ebaystatic.com/pict/300118132027.jpg</GalleryURL> 
      <PrimaryCategoryID>88895</PrimaryCategoryID> 
      <PrimaryCategoryName>Collectibles:Fantasy, Mythical & Magic:Harry Potter:Figurines, Statues</PrimaryCategoryName> 
      <BidCount>0</BidCount> 
      <ConvertedCurrentPrice currencyID="USD">34.99</ConvertedCurrentPrice> 
      <ListingStatus>Active</ListingStatus> 
      <TimeLeft>PT14H27M58S</TimeLeft> 
      <Title>Gentle Giant Harry Potter Phoenix Year 5 Harry Bust</Title> 
      <ShippingCostSummary>
        <ShippingServiceCost currencyID="USD">26.5</ShippingServiceCost> 
        <ShippingType>Calculated</ShippingType> 
      </ShippingCostSummary>
    </Item>
    <Item>
      <ItemID>300118131865</ItemID> 
      <ConvertedBuyItNowPrice currencyID="USD">0.0</ConvertedBuyItNowPrice> 
      <EndTime>2007-06-07T16:51:30.000Z</EndTime> 
      <ViewItemURLForNaturalSearch>http://cgi.ebay.com/Gentle-Giant-Harry-Potter-Phoenix-Draco-Malfoy-Bust_W0QQitemZ300118131865QQcategoryZ88895QQcmdZViewItem</ViewItemURLForNaturalSearch> 
      <GalleryURL>http://thumbs.ebaystatic.com/pict/300118131865.jpg</GalleryURL> 
      <PrimaryCategoryID>88895</PrimaryCategoryID> 
      <PrimaryCategoryName>Collectibles:Fantasy, Mythical & Magic:Harry Potter:Figurines, Statues</PrimaryCategoryName> 
      <BidCount>0</BidCount> 
      <ConvertedCurrentPrice currencyID="USD">34.99</ConvertedCurrentPrice> 
      <ListingStatus>Active</ListingStatus> 
      <TimeLeft>PT14H27M19S</TimeLeft> 
      <Title>Gentle Giant Harry Potter Phoenix Draco Malfoy Bust</Title> 
      <ShippingCostSummary>
        <ShippingServiceCost currencyID="USD">26.5</ShippingServiceCost> 
        <ShippingType>Calculated</ShippingType> 
      </ShippingCostSummary>
    </Item>
    <Item>
      <ItemID>300118131654</ItemID> 
      <ConvertedBuyItNowPrice currencyID="USD">0.0</ConvertedBuyItNowPrice> 
      <EndTime>2007-06-07T16:50:46.000Z</EndTime> 
      <ViewItemURLForNaturalSearch>http://cgi.ebay.com/Gentle-Giant-Harry-Potter-Phoenix-Cho-Chag-Bust_W0QQitemZ300118131654QQcategoryZ88895QQcmdZViewItem</ViewItemURLForNaturalSearch> 
      <GalleryURL>http://thumbs.ebaystatic.com/pict/300118131654.jpg</GalleryURL> 
      <PrimaryCategoryID>88895</PrimaryCategoryID> 
      <PrimaryCategoryName>Collectibles:Fantasy, Mythical & Magic:Harry Potter:Figurines, Statues</PrimaryCategoryName> 
      <BidCount>0</BidCount> 
      <ConvertedCurrentPrice currencyID="USD">34.99</ConvertedCurrentPrice> 
      <ListingStatus>Active</ListingStatus> 
      <TimeLeft>PT14H26M35S</TimeLeft> 
      <Title>Gentle Giant Harry Potter Phoenix Cho Chag Bust</Title> 
      <ShippingCostSummary>
        <ShippingServiceCost currencyID="USD">26.5</ShippingServiceCost> 
        <ShippingType>Calculated</ShippingType> 
      </ShippingCostSummary>
    </Item>
    <TotalItems>5</TotalItems> 
    <ItemSearchURL>http://search.ebay.com/search/search.dll?satitle=harry%2Bpotter%2Bphoenix</ItemSearchURL> 
  </FindItemsResponse>

Sample: Specifying SellerID Values Call

This sample shows how to specify two SellerID values and a maximum number of entries to be returned. This sample searches for items listed by the specified sellers.

Input

You can use SellerID if you want your search results to be filtered so that the items returned are only items sold by a specific seller or by specific sellers. The multiplicity of SellerID is defined as maxOccurs="unbounded" (repeatable) in the schema. If you want to use a URL for your call, and you want to specify multiple values for SellerID, use a comma. For example, specify SellerID=test0,test1. In the following example, two seller IDs, test0 and test1, are specified.

URL format (HTTP GET). See also the non-wrapped version of this URL. For results in a format other than XML, 
specify a different value for responseencoding.

http://open.api.ebay.com/shopping?callname=FindItems
   &responseencoding=XML
   &appid=YourAppIDHere
   &siteid=0
   &version=517
   &SellerID=test0,test1
   &MaxEntries=50

Here is the same input in XML format (HTTP POST). Note that this does not include standard values.

XML format (HTTP POST). Also available are the .txt version of this XML and the NVNV and NV equivalents.

<?xml version="1.0" encoding="utf-8"?>
<FindItemsRequest xmlns="urn:ebay:apis:eBLBaseComponents">
  <SellerID>test0</SellerID>
  <SellerID>test1</SellerID>
  <MaxEntries>50</MaxEntries>
</FindItemsRequest>

Output

If you chose XML as the response encoding type, you would get something like this.

XML format. Also available are the .txt version of this XML and the JSON, NV and SOAP equivalents.

  <?xml version="1.0" encoding="UTF-8" ?> 
  <FindItemsResponse xmlns="urn:ebay:apis:eBLBaseComponents">
    <Timestamp>2007-06-28T00:04:44.327Z</Timestamp> 
    <Ack>Success</Ack> 
    <Build>e517_core_APILW_4873326_R1</Build> 
    <Version>517</Version> 
    <TotalItems>0</TotalItems> 
    <ItemSearchURL>http://search.ebay.com</ItemSearchURL> 
  </FindItemsResponse>

Sample: Basic Call with Affiliate Tracking

This is a basic search for items that would enable you to get commissions using affiliate tracking functionality.

Input

If you use affiliate parameters, you can get commissions based on transactions and based on new user registrations. For information about commissions for affiliates, see the eBay Partner Network. Note that there are no affiliate-related input values shown in the text of the XML-input-format sample below because affiliate parameters are generally specified in the URL.

URL format (HTTP GET). See also the non-wrapped version of this URL. For results in a format other than XML, 
specify a different value for responseencoding.

http://open.api.ebay.com/shopping?callname=FindItems
   &responseencoding=XML
   &appid=YourAppIDHere
   &siteid=0
   &version=565
   &QueryKeywords=harry%20original
   &MaxEntries=1
   &trackingpartnercode=9
   &trackingid=1234567890

Here is the same input in XML format (HTTP POST). Note that this does not include standard values.

XML format (HTTP POST). Also available is the .txt version of this XML.

<?xml version="1.0" encoding="utf-8"?>
<FindItemsRequest xmlns="urn:ebay:apis:eBLBaseComponents">
  <QueryKeywords>harry original</QueryKeywords>
  <MaxEntries>1</MaxEntries>
</FindItemsRequest>

Output

If you chose XML as the response encoding type, you would get something like this.

XML format. Also available are the .txt version of this XML and the SOAP equivalent.

<?xml version="1.0" encoding="UTF-8" ?> 
<FindItemsResponse xmlns="urn:ebay:apis:eBLBaseComponents">
  <Timestamp>2008-05-29T18:51:34.450Z</Timestamp> 
  <Ack>Success</Ack> 
  <Build>e565_core_Bundled_6639382_R1</Build> 
  <Version>565</Version> 
    <Item>
      <ItemID>110255357049</ItemID> 
      <EndTime>2008-05-29T20:38:40.000Z</EndTime> 
      <ViewItemURLForNaturalSearch>http://rover.ebay.com/rover/1/711-53200-19255-0/1?campid=1234567890&customid=&toolid=10012&mpre=http://cgi.ebay.com/Harry-Anderson-Karen-Valentine-Original-6x9-Photo_W0QQitemZ110255357049QQcategoryZ18827QQcmdZViewItem</ViewItemURLForNaturalSearch> 
      <ListingType>Chinese</ListingType> 
      <GalleryURL>http://thumbs.ebaystatic.com/pict/110255357049.jpg</GalleryURL> 
      <PrimaryCategoryID>18827</PrimaryCategoryID> 
      <PrimaryCategoryName>Entertainment Memorabilia:Movie Memorabilia:Photos:1970-79:Black & White</PrimaryCategoryName> 
      <BidCount>0</BidCount> 
      <ConvertedCurrentPrice currencyID="USD">9.99</ConvertedCurrentPrice> 
      <ListingStatus>Active</ListingStatus> 
      <TimeLeft>PT1H47M6S</TimeLeft> 
      <Title>Harry Anderson Karen Valentine Original 6x9" Photo</Title> 
      <ShippingCostSummary>
        <ShippingServiceCost currencyID="USD">6.8</ShippingServiceCost> 
        <ShippingType>Flat</ShippingType> 
      </ShippingCostSummary>
    </Item>
  <TotalItems>72</TotalItems> 
  <ItemSearchURL>http://search.ebay.com/ws/search/SaleSearch?DemandData=1&fsop=32&satitle=harry+original&rover=1234567890</ItemSearchURL>
</FindItemsResponse>

FindItems Change History

Version	Description
553 2008-02-20	ItemSort (modified): Beginning in March 2008, Best Match is the default sort order of search results.
535 2007-10-17	SellerID, SellerIDExclude (doc change): The documentation has been updated to state that the maximum number of sellers that can be specified is 100.
527 2007-08-22	ListingType (added): The ListingType field now is returned, by default.
521 2007-07-11	Item.Location (doc change): The documentation has been corrected to remove Item.Location from the call output. QueryKeywords (modified): The FindItems call now handles URL-encoded input, e.g. you can specify toy%20boat in the QueryKeywords parameter. (doc change) A sample has been added that shows how to specify affiliate parameters.
519 2007-06-27	PictureURL (doc change): The documentation has been corrected to remove PictureURL from the call output. (doc change) A sample has been added that shows how to specify SellerID input values.
515 2007-06-10	(added) New call.

User-Contributed Notes

This document was generated with a customized version of the apireferencedocs tool [0.5M zip].

eBay Shopping API Call Reference Version 573

eBay Shopping API
Call Reference Version 573