eBay Shopping API
|
| Note: This API call is being deprecated and will not be available after July 1, 2010. The functionality provided by this call will be supported in the new Finding API. If you're building new search applications, we recommend you start with the Finding API. |
Searches for items based a query or seller ID. If you use keywords, this call returns items that contain the keywords in the title. Items returned by this call aren't sorted the same way as on the eBay web site; for better sorting, see the Finding API.
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, or you can use FindItemsAdvanced instead to retrieve more items. Store Inventory format (StoresFixedPrice) items are not returned by this call (but they are returned by FindItemsAdvanced).
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. If you are not using the BestMatch search option, the API search results may not match the search results returned by the eBay website. 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.
See also the reference documentation for these calls:
| Output Detail Controls Samples Change History |
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"?> <FindItemsRequest xmlns="urn:ebay:apis:eBLBaseComponents"> <!-- Standard Input Fields --> <MessageID> string </MessageID> <!-- Call-specific Input Fields --> <HideDuplicateItems> boolean </HideDuplicateItems> <ItemSort> SimpleItemSortCodeType </ItemSort> <MaxEntries> int </MaxEntries> <PostalCode> string </PostalCode> <QueryKeywords> string </QueryKeywords> <SellerID> string </SellerID> <!-- ... more SellerID nodes here ... --> <SellerIDExclude> string </SellerIDExclude> <!-- ... more SellerIDExclude nodes here ... --> <SortOrder> SortOrderCodeType </SortOrder> </FindItemsRequest>
| Argument | Type | Occurrence | 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 | |||
| HideDuplicateItems | boolean | Optional |
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:
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. Default: false. |
| ItemSort | SimpleItemSortCodeType | Optional |
Sorts search results based on the value you specify. See the SortOrder field for values that specify whether 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. • 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 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 | Conditional,
repeatable: [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. The value you specify in SellerID is ignored if it is invalid. You can specify a maximum of 100 sellers. |
| SellerIDExclude | string | Optional,
repeatable: [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. |
| 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. |
| Input Detail Controls Samples Change History |
The box below lists all fields that might be returned in the 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).
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 -->
<DuplicateItems> boolean </DuplicateItems>
<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
<ListedShippingServiceCost currencyID="CurrencyCodeType"> AmountType (double) </ListedShippingServiceCost>
<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 | Occurrence | 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 | Conditionally,
repeatable: [0..*] |
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 | Conditionally,
repeatable: [0..*] |
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.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. |
| Call-specific Output Fields | |||
| DuplicateItems | boolean | Conditionally | Indicates whether there are duplicated items not returned by this response when HideDuplicateItems is true in the request. |
| Item | SimpleItemType | Conditionally,
repeatable: [0..*] |
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, the Buy It Now Option becomes unavailable once an auction has a valid bid. Note that the bid must be above any reserve price. |
| Item.BuyItNowAvailable | boolean | Conditionally |
Indicates whether the item has an active Buy It Now option. On most sites, the Buy It Now option is disabled once a valid bid for the item has been accepted. To see if the item was listed with a Buy It Now option, see if the response includes Item.BuyItNowPrice. This field is returned only if the value is true. |
| 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. Some eBay sites also support multi-item Buy It Now auctions, where you can buy multiple items from the same listing at a fixed price. See Item.BuyItNowAvailable. For fixed-price (FixedPriceItem) and Store Inventory listings (StoresFixedPrice), see CurrentPrice or ConvertedCurrentPrice instead. Returned only if an item was listed with a Buy It Now option. For active items, refresh this value every 24 hours to pick up the current conversion rates (if this value has been converted). See:
|
| 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 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. Some eBay sites also support multi-item Buy It Now auctions, where you can buy multiple items from the same listing at a fixed price. See Item.BuyItNowAvailable. For fixed-price (FixedPriceItem) and Store Inventory listings (StoresFixedPrice), see CurrentPrice or ConvertedCurrentPrice instead. Returned only if an item was listed with a Buy It Now option. For active items, refresh this value every 24 hours to pick up the current conversion rates (if this value has been converted). See:
|
| 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. In search results (like the FindItemsAdvanced response), the same EndTime may be returned for multiple results if the results are variations from the same multi-variation listing. |
| 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. In search results (like the FindItemsAdvanced response), the same ItemID may be returned for multiple results if the results are variations from the same multi-variation listing. 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 Deprecated as of version 611.
• Express Deprecated as of version 561.
• FixedPriceItem (out) A basic fixed-price listing with a Quantity of 1. Allows no auction-style bidding. Also known as Buy It Now Only on some sites, this should not to be confused with the BuyItNow option that is available for competitive-bid auctions. Fixed-price listings appear on eBay.com. They are also listed in a 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, 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. This item type can only be specified by sellers who have an eBay Store. Store Inventory listings are listed on eBay.com as well as 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.) |
| 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 .ListedShippingServiceCost |
AmountType (double) | Conditionally |
The listed shipping cost of the item. If multiple items were purchased, this includes the listed ShippingServiceAdditionalCost. In GetSingleItem, this is always returned when ShippingCostSummary is returned, except when the ShippingType is Freight. |
| Item.ShippingCostSummary .ListedShippingServiceCost [ 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 .ShippingServiceCost |
AmountType (double) | Conditionally |
The basic shipping cost of the item. If multiple items were purchased, this includes the ShippingServiceAdditionalCost. In GetSingleItem, this is always returned when ShippingCostSummary is returned, except for when the ShippingType is Freight. |
| 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.
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: • 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). In search results (like the FindItemsAdvanced response), the same TimeLeft may be returned for multiple results if the results are variations from the same multi-variation listing. |
| Item.Title | string | Conditionally |
Name of the item as it appears in the listing or in search and browse results. For US eBay Motors vehicles only: In item-retrieval calls (like GetSingleItem and GetMultipleItems), this value shows the vehicle Make and Model (e.g., "Buick : Skylark"). In finding calls (like FindItemsAdvanced), this value concatenates several Item Specifics: The Make (e.g., "Buick"), Model (e.g., Skylark), Submodel (e.g., Limited), and the seller's customized subtitle (e.g., "Great deal!"). Call GetSingleItem with IncludeSelector=ItemSpecifics to see the individual Item Specifics (in Item.ItemSpecifics). Note: GetSingleItem and FindItemsAdvanced do not return the same Item.Title value for US eBay Motors listings. Here's why: In general, GetSingleItem maps to eBay's View Item page. The eBay Motors Web site's View Item page shows two vehicle titles in the title bar: One title is a label based on the Year, Make, Model, and Submodel (e.g., "1996 Buick Skylark Limited"). The model is included unless it's "Other" or unspecified. The submodel is included if the seller specified a submodel. The other title is a path based on the Make and Model (e.g., "Buick : Skylark"). The Item.Title value in GetSingleItem maps to this path. In general, FindItemsAdvanced maps to eBay's advanced search functionality. The Item.Title value described above for FindItemsAdvanced maps to the item's search result title in the eBay Motors search results page. |
|
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. In search results (like the FindItemsAdvanced response),if the result is a variation from a multi-variation listing, this link to the View Item page is configured to select the applicable variation. |
| 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. |
| Input Output Samples Change History |
This call does not use a detail control mechanism.
| Input Output Detail Controls Change History |
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:
Retrieves a default set of item information based on the supplied keyword ("harry potter pheonix").
Input
This example returns the first 50 items found using the keyword "harry potter phoenix". eBay returns the default set of item information for each item. For more information on making Shopping API calls and the different values you need to specify, see standard values. For a tutorial, see Getting Started with Search in the eBay Shopping API: Specifying JSON Results.
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 SOAP, JSON and NV equivalents. <?xml version="1.0" encoding="utf-8"?> <FindItemsRequest xmlns="urn:ebay:apis:eBLBaseComponents"> <QueryKeywords>harry potter phoenix</QueryKeywords> <MaxEntries>50</MaxEntries> </FindItemsRequest>
Output
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>
Retrieves items associated with two different sellers (specified by their SellerID values).
Input
You can use SellerID to search for items sold by a specific seller. In the schema, the multiplicity of SellerID is maxOccurs="unbounded", which defines it is repeatable (if needed, your search can include items from more than a single seller).
If you are making the call using a URL, specify multiple SellerID values by separating them with a comma. This can be seen in the sample, where two sellers are specified as follows: SellerID=test0,test1
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 NV, SOAP and JSON 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
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>
Retrieves affiliate information in addition to the default item information.
Input
If you are an eBay affiliate, you can get commissions based on certain user actions (such as new user registrations). For details on this program, see eBay Partner Network.
For details on how to use the affiliate parameter values, see affiliate tracking functionality.
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
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>
| Input Output Detail Controls Samples |
| Version | Description |
|---|---|
| 637 2009-09-30 |
|
| 581 2008-09-03 |
|
| 553 2008-02-20 |
|
| 535 2007-10-17 |
|
| 527 2007-08-22 |
|
| 521 2007-07-11 |
|
| 519 2007-06-27 |
|
| 515 2007-06-10 |
|
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.