eBay Shopping API
|
FindPopularItems enables you to search for popular items based on a category or keyword. It evaluates popularity based on criteria such as Watch Count and other criteria as determined by eBay. This call returns WatchCount in addition to item information.
On input, you specify keywords or category IDs. You may use them separately to retrieve items by keyword or category, or combine them to limit the search to a specific item and category combination. For example, you could search for popular items by the keyword "Nikon" or by category Digital Cameras (# 29997), but if you combine keyword and category in a single query, you will get the most popular "Nikon" items in the Digital Camera category.
You can exclude category IDs by specifying CategoryIDExclude and you may use it with QueryKeywords and CategoryID. So similarly, you could search for "Nikon" in all categories except Digital Cameras.
For information about specifying affiliate parameters, see Affiliate URL Parameters and HTTP Header Values.
Some items can be listed in two categories- primary and secondary. For example, a signed, 1st edition copy of Harry Potter and the Philosopher's Stone book might belong to the Antiquarian and Collectible (category #29223) as a primary category and Children's books category (category #279) as a secondary category. If you specify a CategoryID or CategoryIDExclude, be aware that FindPopularItems searches both primary and secondary categories. However, only PrimaryCategoryID is included in the results.
You must specify either a keyword or a category ID in the request. A maximum of 20 items is returned.
Note: FindPopularItems can be slower than FindPopularSearches and FindProducts. Also, due to the way popular item data is cached, you may get a faster response when you run the same query a second time.
FindPopularItems can be a great way to find basic information about popular items. If you need additional information such as Seller Feedback, you can use FindPopularItems with GetSingleItem. First, use FindPopularItems to obtain the ItemID of a popular item. Then use this ItemID as an input in GetSingleItem, along with IncludeSelector set to Details, to obtain the Item.Seller.FeedbackScore in the output( the feedback rating of the seller who is offering this popular item).
| Note: For listings that return Item.DiscountPriceInfo.PricingTreatment set to MAP (Minimum Advertised Price), you are legally required to follow the rules for displaying the price of the item to potential buyers. You are bound by the terms of the API License Agreement to follow these rules. Refer to the API License Agreement for consequences of non-compliance. |
If you discover other useful practices, feel free to add them in the User-Contributed Notes at the bottom of this page.
If you're looking for more tips, try searching the Knowledge Base and Developer Forums.
See also the reference documentation for this call:
| Output Detail Controls Samples Change History User Notes |
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.
<?xml version="1.0" encoding="utf-8"?> <FindPopularItemsRequest xmlns="urn:ebay:apis:eBLBaseComponents"> <!-- Call-specific Input Fields --> <CategoryID> string </CategoryID> <!-- ... more CategoryID values allowed here ... --> <CategoryIDExclude> string </CategoryIDExclude> <!-- ... more CategoryIDExclude values allowed here ... --> <MaxEntries> int </MaxEntries> <QueryKeywords> string </QueryKeywords> <!-- Standard Input Fields --> <MessageID> string </MessageID> </FindPopularItemsRequest>
| Argument | Type | Occurrence | Meaning |
|---|
| Call-specific Input Fields [Jump to standard fields] |
| CategoryID | string | Conditional,
repeatable: [0..*] |
Specify CategoryID to restrict your query to a specific category. Up to 10 categories may be specified. If you are using a URL, and you want to specify more than one CategoryID, separate the values with a comma. For example, to specify Fiction Books and Children's Books, specify CategoryID=377,279. 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 findItemsAdvanced from the Finding API with CategoryHistogram value in the OutputSelector field to retrieve matching categories. Then make another findItemsAdvanced call with the ID of a matching category. CategoryID can be used in combination with QueryKeywords and CategoryIDExclude. To retrieve the most popular items across all categorys, do not submit a CategoryID. Max length: 10. |
| CategoryIDExclude | string | Optional,
repeatable: [0..*] |
Specify this value if you want search results to be filtered so that the popular items returned do not include items that belong to a specific category. CategoryIDExclude is an unbounded field. If you are using a URL, you can separate multiple values with a comma. For example, if you want to specify Records and SuperAudio CDs, specify CategoryIDExclude=306,46354. If you use CategoryIDExclude, it must be used in with QueryKeywords or CategoryID. The CategoryIDExclude input field need not be used if you specified the CategoryID input field. |
| MaxEntries | int | Optional |
Specifies the maximum number of entries to return in a single call. Min: 0. Max: 100. |
| 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. QueryKeywords can be used in combination with CategoryID and CategoryIDExclude. Max length: 350 (characters). |
| Standard Input 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. |
| Input Detail Controls Samples Change History User Notes |
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.
<?xml version="1.0" encoding="utf-8"?>
<FindPopularItemsResponse xmlns="urn:ebay:apis:eBLBaseComponents">
<!-- Call-specific Output Fields -->
<ItemArray> SimpleItemArrayType
<Item> SimpleItemType
<BidCount> int </BidCount>
<ConvertedCurrentPrice> AmountType (double) </ConvertedCurrentPrice>
<DiscountPriceInfo> DiscountPriceInfoType
<MinimumAdvertisedPrice> AmountType (double) </MinimumAdvertisedPrice>
<MinimumAdvertisedPriceExposure> MinimumAdvertisedPriceExposureCodeType </MinimumAdvertisedPriceExposure>
<OriginalRetailPrice> AmountType (double) </OriginalRetailPrice>
<PricingTreatment> PricingTreatmentCodeType </PricingTreatment>
<SoldOffeBay> boolean </SoldOffeBay>
<SoldOneBay> boolean </SoldOneBay>
</DiscountPriceInfo>
<EndTime> dateTime </EndTime>
<GalleryURL> anyURI </GalleryURL>
<ItemID> string </ItemID>
<ListingStatus> ListingStatusCodeType </ListingStatus>
<ListingType> ListingTypeCodeType </ListingType>
<PrimaryCategoryID> string </PrimaryCategoryID>
<PrimaryCategoryName> string </PrimaryCategoryName>
<ShippingCostSummary> ShippingCostSummaryType
<ShippingType> ShippingTypeCodeType </ShippingType>
</ShippingCostSummary>
<TimeLeft> duration </TimeLeft>
<Title> string </Title>
<ViewItemURLForNaturalSearch> anyURI </ViewItemURLForNaturalSearch>
<WatchCount> int </WatchCount>
</Item>
<!-- ... more Item nodes allowed here ... -->
</ItemArray>
<!-- 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 allowed here ... -->
<LongMessage> string </LongMessage>
<SeverityCode> SeverityCodeType </SeverityCode>
<ShortMessage> string </ShortMessage>
</Errors>
<!-- ... more Errors nodes allowed here ... -->
<Timestamp> dateTime </Timestamp>
<Version> string </Version>
</FindPopularItemsResponse>
| Return Value | Type | Occurrence | Meaning |
|---|
| Call-specific Output Fields [Jump to standard fields] |
| ItemArray | SimpleItemArrayType | Always | A list of active items that were listed with the requested product. |
| ItemArray.Item | SimpleItemType | Always,
repeatable: [1..*] |
Contains data for an item listing. |
| ItemArray.Item.BidCount | int | Always |
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. FindPopularItems: For fixed-price listings, the BidCount value is the total number of items purchased so far (in the listing's lifetime). |
|
ItemArray.Item .ConvertedCurrentPrice |
AmountType (double) | Always |
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) listings, 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:
|
|
ItemArray.Item .DiscountPriceInfo |
DiscountPriceInfoType | Conditionally |
This container provides information for an item that has a Strikethrough Price (STP) or a Minimum Advertised Price (MAP) discount pricing treatment. STP and MAP applies to only fixed price, BIN items. STP is available on the US, UK, and German (DE) sites, while MAP is available only on the US site. Discount pricing is available to qualified sellers (and their associated developers) who participate in the Discount Pricing Program. Once qualified, sellers receive a "sepcial account flag" (SAF) that allows them to apply Discount Pricing to both MSKU and Non-MSKU items. |
|
ItemArray.Item .DiscountPriceInfo .MinimumAdvertisedPrice |
AmountType (double) | Conditionally |
A value equal to the agreed upon minimum advertised price. The minimum advertised price is an agreed upon price that is set by the suppliers/OEMs and the retailers/sellers. The minimum advertised price is the lowest price for which an item can be advertised. Large volume sellers can negotiate with the suppliers/OEMs to offer certain items below the set minimum advertised price. eBay does not maintain or validate the agreed upon minimum advertised price; the seller is responsible for setting this value in accordance with their agreement with the supplier/OEMs. MAP pricing treatments apply to only fixed price, BIN items listed on the eBay US site. |
|
ItemArray.Item .DiscountPriceInfo .MinimumAdvertisedPriceExposure |
MinimumAdvertisedPriceExposureCodeType | Conditionally |
If an item listing qualifies it to be listed as a MAP item (PricingTreatment returns MAP), the item price cannot be directly displayed on the page containing the item. When listing a MAP item, the seller stipulates how they want the buyer to view the price of the item by setting this field to either PreCheckout or DuringCheckout. If this feild is not set for a MAP item, the treatment defaults to PreCheckout. If this field is set to PreCheckout, the buyer must click a link (or button) to view the item price on a different page (such as in a pop-up window). If this field is set to DuringCheckout, the StartPrice must be shown only when the buyer in the eBay checkout flow. MAP items are supported only on the eBay US site. Applicable values: • CustomCode (out) Reserved for future use. • DuringCheckout (out) DuringCheckout specifies that the discounted price must be shown on the eBay checkout flow page. • None (out) None means the discount price is not shown via either PreCheckout nor DuringCheckout. • PreCheckout (out) PreCheckout specifies that the buyer must click a link (or a button) to navigate to a separate page (or window) that displays the discount price. |
|
ItemArray.Item .DiscountPriceInfo .OriginalRetailPrice |
AmountType (double) | Conditionally |
This field specifies the price to which the discounted-price display treatment will be applied (for example, a strikethrough price). The discounted price of an item (specified in the CurrentPrice field) is the BIN price and is less than the OriginalRetailPrice of the item. See Displaying Discount Pricing Information to Buyers for guidelines on displaying STP and MAP items. |
|
ItemArray.Item .DiscountPriceInfo .PricingTreatment |
PricingTreatmentCodeType | Conditionally |
This field denotes whether or not an item qualifies for a discount pricing treatment display. If a seller lists an item with DiscountPriceInfo values, the item response container will include a DiscountPriceInfo container with this field set to either STP, MAP, or None. If this field is set to MAP, you must abide by the rules for displaying MAP items, as described in MinimumAdvertisedPriceExposure. Important: For listings that return PricingTreatment set to MAP, you are legally required to follow the rules for displaying the price of the item to potential buyers. You are bound by the terms of the API License Agreement to follow these rules. Refer to the API License Agreement for consequences of non-compliance. Applicable values: • CustomCode (out) Reserved for future use. • MAP (out) MAP stands for Minimum Advertised Price. • None (out) None means the item does not qualify for either STP or MAP pricing. • STP (out) STP stands for Strikethrough Pricing. |
|
ItemArray.Item .DiscountPriceInfo.SoldOffeBay |
boolean | Conditionally |
Used by the eBay UK and eBay Germany (DE) sites, this field indicates that the discount price (specified as currentPrice) is the price for which the seller offered the same item for sale on a web site or offline store other than eBay in the previous 30 days. The discount price is always in reference to the seller's own price for the item. In the event both soldOffeBay and soldOneBay fields are set, soldOneBay takes precedence. |
|
ItemArray.Item .DiscountPriceInfo.SoldOneBay |
boolean | Conditionally |
Used by the eBay UK and eBay Germany (DE) sites, this field indicates that the discount price (specified as CurrentPrice) is the price for which the seller offered the same (or similar) item for sale on eBay within the previous 30 days. The discount price is always in reference to the seller's own price for the item. In the event both soldOffeBay and soldOneBay fields are set, soldOneBay takes precedence. |
| ItemArray.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). |
| ItemArray.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. |
| ItemArray.Item.ItemID | string | Always |
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). |
| ItemArray.Item.ListingStatus | ListingStatusCodeType | Always |
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. |
| ItemArray.Item.ListingType | ListingTypeCodeType | Always |
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. • 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. • 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. • 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. • Unknown (out) Unknown auction type. (This is not normally used.) (Not all values in ListingTypeCodeType apply to this field.) |
|
ItemArray.Item .PrimaryCategoryID |
string | Always | Numeric ID of the first (or only) category in which the item is listed. (Listings can appear in more than one category.) |
|
ItemArray.Item .PrimaryCategoryName |
string | Always | 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). |
|
ItemArray.Item .ShippingCostSummary |
ShippingCostSummaryType | Always |
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. |
|
ItemArray.Item .ShippingCostSummary .ShippingType |
ShippingTypeCodeType | Always |
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. |
| ItemArray.Item.TimeLeft | duration | Always | 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). |
| ItemArray.Item.Title | string | Always |
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"). Note: GetSingleItem does 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. |
|
ItemArray.Item .ViewItemURLForNaturalSearch |
anyURI | Always | 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 ?. |
| ItemArray.Item.WatchCount | int | Always | Number of users who have placed the item on their Watch list. |
| Standard Output 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. |
| Input Output Samples Change History User Notes |
This call does not support varying Detail Levels. You do not need to pass DetailLevel in the request.
| Input Output Detail Controls Change History User Notes |
New to making API calls? Please see Making an API Call.
Note: Some data in these samples might no longer be active. If necessary, you can substitute current data in your requests.
Available samples:
Retrieves popular items based on a keyword that you provide.
Input
This example returns popular items that are associated with a specified keyword.
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=FindPopularItems&
responseencoding=XML&
appid=YourAppIDHere&
siteid=0&
version=531&
QueryKeywords=harry%20original
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"?> <FindPopularItemsRequest xmlns="urn:ebay:apis:eBLBaseComponents"> <QueryKeywords>harry original</QueryKeywords> </FindPopularItemsRequest>
Output
XML format. Also available is the .txt version of this XML. <?xml version="1.0" encoding="UTF-8" ?> <FindPopularItemsResponse xmlns="urn:ebay:apis:eBLBaseComponents"> <Timestamp>2007-09-10T22:10:57.546Z</Timestamp> <Ack>Success</Ack> <Build>e531_core_APILW2_5302589_R1</Build> <Version>531</Version> <ItemArray> <Item> <ItemID>330000921552</ItemID> <EndTime>2007-09-14T23:22:59.000Z</EndTime> <ViewItemURLForNaturalSearch>http://cgi.ebay.com/Harry-Potter-And-The-Chamber-Of-Secrets-Original-S_W0QQitemZ330000921552QQcategoryZ307QQcmdZViewItem</ViewItemURLForNaturalSearch> <ListingType>Chinese</ListingType> <GalleryURL>http://thumbs.ebaystatic.com/pict/330000921552.jpg</GalleryURL> <PrimaryCategoryID>307</PrimaryCategoryID> <PrimaryCategoryName>Music:CDs</PrimaryCategoryName> <BidCount>1</BidCount> <ConvertedCurrentPrice currencyID="USD">3.9</ConvertedCurrentPrice> <ListingStatus>Active</ListingStatus> <TimeLeft>P6DT23H42M12S</TimeLeft> <Title>Harry Potter And The Chamber Of Secrets - Original S...</Title> <ShippingCostSummary> <ShippingServiceCost currencyID="USD">2.99</ShippingServiceCost> <ShippingType>Flat</ShippingType> </ShippingCostSummary> <WatchCount>2</WatchCount> </Item> <Item> <ItemID>170000840407</ItemID> <EndTime>2009-09-06T00:34:42.000Z</EndTime> <ViewItemURLForNaturalSearch>http://cgi.ebay.com/Harry-Potter-And-The-Chamber-Of-Secrets-Original-S_W0QQitemZ170000840407QQcategoryZ307QQcmdZViewItem</ViewItemURLForNaturalSearch> <ListingType>Chinese</ListingType> <PrimaryCategoryID>307</PrimaryCategoryID> <PrimaryCategoryName>Music:CDs</PrimaryCategoryName> <BidCount>1</BidCount> <ConvertedCurrentPrice currencyID="USD">5.0</ConvertedCurrentPrice> <ListingStatus>Active</ListingStatus> <TimeLeft>P729DT53M55S</TimeLeft> <Title>Harry Potter And The Chamber Of Secrets - Original S...</Title> <ShippingCostSummary> <ShippingType>NotSpecified</ShippingType> </ShippingCostSummary> <WatchCount>0</WatchCount> </Item> </ItemArray> </FindPopularItemsResponse>
Retrieves popular items based on a keyword that you provide, but the results exclude items found in a specific eBay Category.
Input
This example finds popular items associated with the keyword "potter". Because the query uses CategoryIDExlcude for Category #279 (Children's Books), items in that Category are not returned.
You might construct a query like this to eliminate popular "Harry Potter" Children's books from the results; if you are not interested in children's books, you can exclude them from your search 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=FindPopularItems&
responseencoding=XML&
appid=YourAppIDHere&
siteid=0&
version=531&
QueryKeywords=potter&
CategoryIDExclude=279
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"?> <FindPopularItemsRequest xmlns="urn:ebay:apis:eBLBaseComponents"> <QueryKeywords>potter</QueryKeywords> <CategoryIDExclude>279</CategoryIDExclude> </FindPopularItemsRequest>
Output
XML format. Also available is the .txt version of this XML. <?xml version="1.0" encoding="utf-8"?> <FindPopularItemsResponse xmlns="urn:ebay:apis:eBLBaseComponents"> <Timestamp>2007-09-19T02:09:50.875Z</Timestamp> <Ack>Success</Ack> <Build>e531_intl_APILW2_5348019_R1</Build> <Version>531</Version> <ItemArray> <Item> <ItemID>102000050018</ItemID> <EndTime>2009-09-17T09:40:00.000Z</EndTime> <ViewItemURLForNaturalSearch>http://cgi.ebay.com/Solomon-Super-Gallery-PDP-Core-Harry-Potter_W0QQitemZ102000050018QQcategoryZ617QQcmdZViewItem</ViewItemURLForNaturalSearch> <ListingType>Chinese</ListingType> <GalleryURL>http://thumbs.ebaystatic.com/pict/102000050018.jpg</GalleryURL> <PrimaryCategoryID>617</PrimaryCategoryID> <PrimaryCategoryName>DVDs & Movies:DVD, HD DVD & Blu-ray</PrimaryCategoryName> <BidCount>13</BidCount> <ConvertedCurrentPrice currencyID="USD">255.0</ConvertedCurrentPrice> <ListingStatus>Active</ListingStatus> <TimeLeft>P729DT7H30M10S</TimeLeft> <Title>Solomon Super Gallery PDP Core Harry Potter</Title> <ShippingCostSummary> <ShippingType>NotSpecified</ShippingType> </ShippingCostSummary> <WatchCount>15</WatchCount> </Item> <Item> <ItemID>102000631919</ItemID> <EndTime>2009-09-17T09:40:00.000Z</EndTime> <ViewItemURLForNaturalSearch>http://cgi.ebay.com/GwQ-FindItemsAdvanced-CH_W0QQitemZ102000631919QQcategoryZ617QQcmdZViewItem</ViewItemURLForNaturalSearch> <ListingType>Chinese</ListingType> <GalleryURL>http://thumbs.ebaystatic.com/pict/102000631919.jpg</GalleryURL> <PrimaryCategoryID>617</PrimaryCategoryID> <PrimaryCategoryName>DVDs & Movies:DVD, HD DVD & Blu-ray</PrimaryCategoryName> <BidCount>13</BidCount> <ConvertedCurrentPrice currencyID="USD">255.0</ConvertedCurrentPrice> <ListingStatus>Active</ListingStatus> <TimeLeft>P729DT7H30M10S</TimeLeft> <Title>GwQ FindItemsAdvanced CH</Title> <ShippingCostSummary> <ShippingType>NotSpecified</ShippingType> </ShippingCostSummary> <WatchCount>14</WatchCount> </Item> <Item> <ItemID>102000050019</ItemID> <EndTime>2009-09-17T09:40:00.000Z</EndTime> <ViewItemURLForNaturalSearch>http://cgi.ebay.com/Solomon-Super-Gallery-PDP-Core-Harry-Potter_W0QQitemZ102000050019QQcategoryZ617QQcmdZViewItem</ViewItemURLForNaturalSearch> <ListingType>Chinese</ListingType> <GalleryURL>http://thumbs.ebaystatic.com/pict/102000050019.jpg</GalleryURL> <PrimaryCategoryID>617</PrimaryCategoryID> <PrimaryCategoryName>DVDs & Movies:DVD, HD DVD & Blu-ray</PrimaryCategoryName> <BidCount>3</BidCount> <ConvertedCurrentPrice currencyID="USD">26.0</ConvertedCurrentPrice> <ListingStatus>Active</ListingStatus> <TimeLeft>P729DT7H30M10S</TimeLeft> <Title>Solomon Super Gallery PDP Core Harry Potter</Title> <ShippingCostSummary> <ShippingType>NotSpecified</ShippingType> </ShippingCostSummary> <WatchCount>5</WatchCount> </Item> <Item> <ItemID>220000510279</ItemID> <EndTime>2009-09-17T10:34:53.000Z</EndTime> <ViewItemURLForNaturalSearch>http://cgi.ebay.com/Harry-Potter-and-the-Chamber-of-Secrets-by-J-K-Row_W0QQitemZ220000510279QQcategoryZ29792QQcmdZViewItem</ViewItemURLForNaturalSearch> <ListingType>Chinese</ListingType> <PrimaryCategoryID>29792</PrimaryCategoryID> <PrimaryCategoryName>Books:Audiobooks</PrimaryCategoryName> <BidCount>1</BidCount> <ConvertedCurrentPrice currencyID="USD">3.0</ConvertedCurrentPrice> <ListingStatus>Active</ListingStatus> <TimeLeft>P729DT8H25M3S</TimeLeft> <Title>Harry Potter and the Chamber of Secrets by J. K. Row...</Title> <ShippingCostSummary> <ShippingType>NotSpecified</ShippingType> </ShippingCostSummary> <WatchCount>2</WatchCount> </Item> <Item> <ItemID>3601373295</ItemID> <EndTime>2009-09-13T10:53:13.000Z</EndTime> <ViewItemURLForNaturalSearch>http://cgi.ebay.com/Harry-Potter-and-the-Chamber-of-Secrets-2003-DVD_W0QQitemZ3601373295QQcategoryZ617QQcmdZViewItem</ViewItemURLForNaturalSearch> <ListingType>Chinese</ListingType> <GalleryURL>http://thumbs.ebaystatic.com/pict/3601373295.jpg</GalleryURL> <PrimaryCategoryID>617</PrimaryCategoryID> <PrimaryCategoryName>DVDs & Movies:DVD, HD DVD & Blu-ray</PrimaryCategoryName> <BidCount>3</BidCount> <ConvertedCurrentPrice currencyID="USD">7.1</ConvertedCurrentPrice> <ListingStatus>Active</ListingStatus> <TimeLeft>P725DT8H43M23S</TimeLeft> <Title>Harry Potter and the Chamber of Secrets (2003, DVD)</Title> <ShippingCostSummary> <ShippingServiceCost currencyID="USD">2.49</ShippingServiceCost> <ShippingType>Flat</ShippingType> </ShippingCostSummary> <WatchCount>1</WatchCount> </Item> <Item> <ItemID>220000280110</ItemID> <EndTime>2009-09-17T10:34:53.000Z</EndTime> <ViewItemURLForNaturalSearch>http://cgi.ebay.com/Harry-Potter_W0QQitemZ220000280110QQcategoryZ1463QQcmdZViewItem</ViewItemURLForNaturalSearch> <ListingType>Chinese</ListingType> <PrimaryCategoryID>1463</PrimaryCategoryID> <PrimaryCategoryName>Collectibles:Trading Cards:Phone Cards</PrimaryCategoryName> <BidCount>3</BidCount> <ConvertedCurrentPrice currencyID="USD">1.0</ConvertedCurrentPrice> <ListingStatus>Active</ListingStatus> <TimeLeft>P729DT8H25M3S</TimeLeft> <Title>Harry Potter.</Title> <ShippingCostSummary> <ShippingType>NotSpecified</ShippingType> </ShippingCostSummary> <WatchCount>1</WatchCount> </Item> <Item> <ItemID>3601374166</ItemID> <EndTime>2009-09-17T11:07:17.000Z</EndTime> <ViewItemURLForNaturalSearch>http://cgi.ebay.com/GwQ-FindItemsAdvanced-CH_W0QQitemZ3601374166QQcategoryZ617QQcmdZViewItem</ViewItemURLForNaturalSearch> <ListingType>Chinese</ListingType> <GalleryURL>http://thumbs.ebaystatic.com/pict/3601374166.jpg</GalleryURL> <PrimaryCategoryID>617</PrimaryCategoryID> <PrimaryCategoryName>DVDs & Movies:DVD, HD DVD & Blu-ray</PrimaryCategoryName> <BidCount>3</BidCount> <ConvertedCurrentPrice currencyID="USD">7.1</ConvertedCurrentPrice> <ListingStatus>Active</ListingStatus> <TimeLeft>P729DT8H57M27S</TimeLeft> <Title>GwQ FindItemsAdvanced CH</Title> <ShippingCostSummary> <ShippingServiceCost currencyID="USD">2.49</ShippingServiceCost> <ShippingType>Flat</ShippingType> </ShippingCostSummary> <WatchCount>1</WatchCount> </Item> <Item> <ItemID>170001134829</ItemID> <EndTime>2007-09-21T20:10:06.000Z</EndTime> <ViewItemURLForNaturalSearch>http://cgi.ebay.com/SDK-item-title_W0QQitemZ170001134829QQcategoryZ378QQcmdZViewItem</ViewItemURLForNaturalSearch> <ListingType>FixedPriceItem</ListingType> <PrimaryCategoryID>378</PrimaryCategoryID> <PrimaryCategoryName>Books:Nonfiction Books</PrimaryCategoryName> <ConvertedCurrentPrice currencyID="USD">10.0</ConvertedCurrentPrice> <ListingStatus>Active</ListingStatus> <TimeLeft>P2DT18H16S</TimeLeft> <Title>SDK item title</Title> <ShippingCostSummary> <ShippingServiceCost currencyID="USD">1.0</ShippingServiceCost> <ShippingType>Flat</ShippingType> </ShippingCostSummary> <WatchCount>0</WatchCount> </Item> <Item> <ItemID>170001134913</ItemID> <EndTime>2007-09-21T23:06:12.000Z</EndTime> <ViewItemURLForNaturalSearch>http://cgi.ebay.com/Promo-Item_W0QQitemZ170001134913QQcategoryZ378QQcmdZViewItem</ViewItemURLForNaturalSearch> <ListingType>FixedPriceItem</ListingType> <PrimaryCategoryID>378</PrimaryCategoryID> <PrimaryCategoryName>Books:Nonfiction Books</PrimaryCategoryName> <ConvertedCurrentPrice currencyID="USD">10.0</ConvertedCurrentPrice> <ListingStatus>Active</ListingStatus> <TimeLeft>P2DT20H56M22S</TimeLeft> <Title>Promo Item</Title> <ShippingCostSummary> <ShippingServiceCost currencyID="USD">1.0</ShippingServiceCost> <ShippingType>Flat</ShippingType> </ShippingCostSummary> <WatchCount>0</WatchCount> </Item> <Item> <ItemID>170000840407</ItemID> <EndTime>2009-09-17T09:32:14.000Z</EndTime> <ViewItemURLForNaturalSearch>http://cgi.ebay.com/Harry-Potter-And-The-Chamber-Of-Secrets-Original-S_W0QQitemZ170000840407QQcategoryZ307QQcmdZViewItem</ViewItemURLForNaturalSearch> <ListingType>Chinese</ListingType> <PrimaryCategoryID>307</PrimaryCategoryID> <PrimaryCategoryName>Music:CDs</PrimaryCategoryName> <BidCount>1</BidCount> <ConvertedCurrentPrice currencyID="USD">5.0</ConvertedCurrentPrice> <ListingStatus>Active</ListingStatus> <TimeLeft>P729DT7H22M24S</TimeLeft> <Title>Harry Potter And The Chamber Of Secrets - Original S...</Title> <ShippingCostSummary> <ShippingType>NotSpecified</ShippingType> </ShippingCostSummary> <WatchCount>0</WatchCount> </Item> <Item> <ItemID>190000456297</ItemID> <EndTime>2009-09-17T09:40:00.000Z</EndTime> <ViewItemURLForNaturalSearch>http://cgi.ebay.com/harry-potter-gwq-minimium_W0QQitemZ190000456297QQcategoryZ617QQcmdZViewItem</ViewItemURLForNaturalSearch> <ListingType>Chinese</ListingType> <PrimaryCategoryID>617</PrimaryCategoryID> <PrimaryCategoryName>DVDs & Movies:DVD, HD DVD & Blu-ray</PrimaryCategoryName> <BidCount>1</BidCount> <ConvertedCurrentPrice currencyID="USD">1.0</ConvertedCurrentPrice> <ListingStatus>Active</ListingStatus> <TimeLeft>P729DT7H30M10S</TimeLeft> <Title>harry potter gwq minimium</Title> <ShippingCostSummary> <ShippingType>NotSpecified</ShippingType> </ShippingCostSummary> <WatchCount>0</WatchCount> </Item> </ItemArray> </FindPopularItemsResponse>
| Input Output Detail Controls Samples User Notes |
| Version | Description |
|---|---|
| 723 2011-05-25 |
|
| 637 2009-09-30 |
|
| 565 2008-05-14 |
|
| 531 2007-21-09 |
|
| Input Output Detail Controls Samples Change History User Notes |
Copyright © 2006–2013 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.