GET/most_watched_items
This method retrieves items with the highest watch counts in a specific category.
The leaf category for which to retrieve items with the highest watch counts is specified by its category_id value. Up to 50 items can be returned for a specific category using this method. The number of items to return using this method can be specified through the max_result query parameter. If this parameter is not used, the top 20 most watched items will be returned for the specified category.
A successful call returns details about the most watched items in a specific category, such as the watch count, current price, shipping cost, and basic information about the listing. Returned items are ranked in descending order with the highest watch count appearing first.
Input
Resource URI
This method is not supported in Sandbox environment.
URI parameters
| Parameter | Type | Description |
|---|---|---|
| category_id | string | This query parameter can be used to specify the leaf category from which to retrieve most watched items. The list of eBay category IDs is not published and category IDs are not all the same across all the eBay marketplaces. You can use the following techniques to find a category by site:
Note: If no category ID is input though this parameter, category 9355 will be used by default.Maximum: 1 Occurrence: Required |
| max_results | integer | This query parameter can be used to specify the maximum number of most watched items to return from the specified category. Default value: 20 Min value: 1 Max value: 50 Occurrence: Optional |
HTTP request headers
All requests made to eBay REST operations require you to provide the Authorization HTTP header for authentication authorization.
The table below shows additional HTTP request headers that are either required, conditionally required, or strongly recommended for this method. Other standard HTTP request headers- opens rest request components page (not in this table) can also be used, but they are optional.
| Header | Type | Description |
|---|---|---|
| X-EBAY-C-MARKETPLACE-ID | string | This header identifies the seller's eBay marketplace. It is required for all marketplaces outside of the US. Note: If the marketplace ID value is invalid or missing, the default value of EBAY_US is used.See MarketplaceIdEnum for a list of supported marketplaces. Default: EBAY_US Occurrence: Strongly Recommended |
| X-EBAY-C-ENDUSERCTX | string | This header can be used to pass in affiliate credentials to return item affiliate information. For more information, see Header for affiliate information. Occurrence: Optional |
| Accept-Language | string | This header is used to indicate the natural language and locale preferred by the user for the response. This header is required when targeting a specific locale of a marketplace that supports multiple locales. For example:
Occurrence: Conditional |
OAuth scope
This request requires an access token created with the client credentials grant flow, using one or more scopes from the following list (please check your Application Keys page for a list of OAuth scopes available to your application):
https://api.ebay.com/oauth/api_scope/buy.marketing
See OAuth access tokens for more information.
Request payload
This call has no payload.
Request fields
This call has no field definitions.
Output
HTTP response headers
This call has no response headers.
Response payload
Response fields
| Output container/field | Type | Description |
|---|---|---|
| mostWatchedItems | array of MostWatchedItem | This array returns a list of most watched items matching the input criteria. Occurrence: Conditional |
| mostWatchedItems.bidCount | integer | This integer value indicates the total number of bids that have been placed for an auction item. Occurrence: Conditional |
| mostWatchedItems.category | Category | The ID of the leaf category for this item. Occurrence: Conditional |
| mostWatchedItems.category.categoryId | string | The unique identifier of the leaf category for this item. A leaf category is the lowest level in that category and has no children. Occurrence: Conditional |
| mostWatchedItems.category.categoryName | string | The name of the category the item is listed in. Occurrence: Conditional |
| mostWatchedItems.currentBidPrice | Amount | The container that returns the current highest bid for an auction item. Occurrence: Conditional |
| mostWatchedItems.currentBidPrice.currency | CurrencyCodeEnum | The three-letter ISO 4217 code representing the currency of the amount in the value field. Occurrence: Conditional |
| mostWatchedItems.currentBidPrice.value | string | The monetary amount, in the currency specified by the currency field. Occurrence: Conditional |
| mostWatchedItems.galleryImageUrl | string | The URL for the image used as the Gallery thumbnail. Occurrence: Always |
| mostWatchedItems.itemEndDate | string | A timestamp that indicates the date and time a listing is scheduled to end. Occurrence: Conditional |
| mostWatchedItems.itemId | string | The unique RESTful identifier of the item. Occurrence: Always |
| mostWatchedItems.itemLocation | ItemLocation | This container returns the 2-digit ISO code of the country in which the item is location. Occurrence: Conditional |
| mostWatchedItems.itemLocation.country | CountryCodeEnum | The two-letter ISO 3166 standard code that indicates the country in which the item is located. Occurrence: Conditional |
| mostWatchedItems.itemWebUrl | string | The URL to the View Item page of the item. Occurrence: Conditional |
| mostWatchedItems.listingMarketplaceId | MarketplaceIdEnum | The unique identifier of the eBay marketplace of the listing. Occurrence: Always |
| mostWatchedItems.price | Amount | The price of the item. Occurrence: Conditional |
| mostWatchedItems.price.currency | CurrencyCodeEnum | The three-letter ISO 4217 code representing the currency of the amount in the value field. Occurrence: Conditional |
| mostWatchedItems.price.value | string | The monetary amount, in the currency specified by the currency field. Occurrence: Conditional |
| mostWatchedItems.shippingCost | Amount | The final shipping cost of the item. Occurrence: Always |
| mostWatchedItems.shippingCost.currency | CurrencyCodeEnum | The three-letter ISO 4217 code representing the currency of the amount in the value field. Occurrence: Conditional |
| mostWatchedItems.shippingCost.value | string | The monetary amount, in the currency specified by the currency field. Occurrence: Conditional |
| mostWatchedItems.shippingCostType | string | Indicates the type of shipping used to ship the item. Possible values are Occurrence: Always |
| mostWatchedItems.subtitle | string | A subtitle is optional and allows the seller to provide more information about the item, possibly including keywords that may assist with search results. Occurrence: Conditional |
| mostWatchedItems.title | string | The title of the item as its appears on the listing. Occurrence: Always |
| mostWatchedItems.watchCount | integer | The number of users that have added the item to their watch list. Occurrence: Conditional |
HTTP status codes
This call can return one of the following HTTP status codes. For an overview of the status codes, see HTTP status codes in Using eBay RESTful APIs.
| Status | Meaning |
|---|---|
| 200 | OK |
| 400 | Bad Request |
| 500 | Internal Server Error |
Error codes
For more on errors, plus the codes of other common errors, see Handling errors.
| Code | Domain | Category | Meaning |
|---|---|---|---|
| 70000 | API_MARKETING | APPLICATION | There was a problem with an eBay internal system or process. Contact eBay developer support for assistance. |
| 70004 | API_MARKETING | REQUEST | The category id {categoryId} is invalid. |
| 70100 | API_MARKETING | REQUEST | The 'max_results' value must be a positive integer from 1 up to 50. |
Warnings
This call has no warnings.
Samples
New to making API calls? Please see Making a Call.
Note: Identifiers, such as order IDs or user IDs, and personal data in these samples might be anonymized or may no longer be active on eBay. If necessary, substitute current, relevant eBay data in your requests.
Sample 1: Retrieve items with the highest watch count in a category
This method can be used to retrieve the items with the highest watch count in a specified category.
Input
The category_id URI parameter, which specifies the category for which to retrieve items, is used in this sample. This parameter is used to find most-watched items in a specific category. The max_result URI parameter is also used to limit the result set to only the top 6 most watched items.
GEThttps://api.ebay.com/buy/marketing/v1/most_watched_items?category_id=11116&max_results=6
Output
If the call is successful, a list of items with the highest watch count, that meet the input criteria, are returned. This includes information such as each item's ID, watch count, category information, marketplace, shipping cost, and price.