feed APIv1_beta.15.0

getItemSnapshotFeed

GET
/item_snapshot

The Hourly Snapshot feed file is generated each hour every day for all categories. This method lets you download an Hourly Snapshot TSV_GZIP (tab separated value gzip) feed file containing the details of all the items that have changed within the specified day and hour for a specific category. This means to generate the 8AM file of items that have changed from 8AM and 8:59AM, the service starts at 9AM. You can retrieve the 8AM snapshot file at 10AM.

Note: Filters are applied to the feed files. For details, see Feed File Filters. When curating the items returned, be sure to code as if these filters are not applied as they can be changed or removed in the future.

You can use the response from this method to update the item details of items stored in your database. By comparing the value of itemSnapshotDate for the same item you will be able to tell which information is the latest.

Important: When the value of the availability column is UNAVAILABLE, only the itemId and availability columns are populated.

URLs for this method

  • Production URL: https://api.ebay.com/buy/feed/v1_beta/
  • Sandbox URL: https://api.sandbox.ebay.com/buy/feed/v1_beta/

Downloading feed files

Hourly snapshot feed files are binary gzip files. If the file is larger than 100 MB, the download must be streamed in chunks. You specify the size of the chunks in bytes using the Range request header. The Content-range response header indicates where in the full resource this partial chunk of data belongs and the total number of bytes in the file. For more information about using these headers, see Retrieving a gzip feed file.

Note: The response is always a TSV_GZIP file. However for documentation purposes, the response is shown as JSON fields so that the value returned in each column can be explained. The order of the response fields, shows you the order of the columns in the feed file.

Restrictions

For a list of supported sites and other restrictions, see API Restrictions.

Input

Resource URI (production)

GET https://api.ebay.com/buy/feed/v1_beta/item_snapshot?

URI parameters

ParameterTypeDescription
category_idstringAn eBay top-level category ID of the items to be returned in the feed file.

The list of eBay category IDs changes over time and category IDs are not the same across all the eBay marketplaces. To get a list of the top-level categories for a marketplace, you can use the Taxonomy API getCategoryTree method. This method retrieves the complete category tree for the marketplace. The top-level categories are identified by the categoryTreeNodeLevel field.

For example:
  "categoryTreeNodeLevel": 1

For details see Get Categories for Buy APIs.

Restriction: Must be a top-level category

Occurrence: Required

snapshot_datestringThe hour of the incremental feed file you want, for a particular day. There are always 14 days of Hourly Snapshot feed files available.

If you specify that you want the 9AM file for July 15, 2017 (2017-07-15T09:00:00.000Z), the data in the feed file will be items that changed after 9AM on July 15, 2017.

Restrictions:

Files are generated on the hour, so minutes and seconds are always zeros.
   (2017-07-12T09:00:00.000Z)

Format: UTC format (yyyy-MM-ddThh:00:00.000Z)

Occurrence: Required

HTTP request headers

All requests made to eBay REST operations require you to provide the Authorization HTTP header for authentication authorization.

HeaderTypeDescription
X-EBAY-C-MARKETPLACE-IDstringThe ID of the eBay marketplace where the item is hosted. Note: This value is case sensitive.

For example:
  X-EBAY-C-MARKETPLACE-ID = EBAY_US

For a list of supported sites see, API Restrictions.

Occurrence: Required

RangestringThis header specifies the range in bytes of the chunks of the gzip file being returned.

Format: bytes=startpos-endpos

For example, the following retrieves the first 10 MBs of the feed file.

  Range bytes=0-10485760

For more information about using this headers, see Retrieving a gzip feed file.

Maximum: 100 MB (10MB in the Sandbox)

Occurrence: Required

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.item.feed

See OAuth access tokens for more information.

Output

HTTP response headers

See HTTP response headers for details.

HeaderMeaning
Content-rangeThe content-range response header indicates where in the full resource this partial chunk of data belongs. It returns the lower and upper values in bytes (specified by the Range header) of the chunk and the total size of the file being downloaded in bytes.

Maximum range: 100 MB

The following is an example of a content-range response, where 0-10 is the lower and upper limit in bytes and 1000 is the total size of the file in bytes.

  0-10/1000

The following example of a content-range response indicates the value of the Range header is invalid and a 416 status code is returned.

   */1000

For more information and examples, see Retrieving a gzip feed file.
Last-ModifiedReturns the generated date of the feed file, which will be the latest file available. For example:
Last-Modified  Wed, 21 Oct 2015 07:28:00 GMT

Important: The response of this call is always a TSV_GZIP file. However, the response is shown as JSON fields for each column so that the value returned in each column can be explained. The order in which the response fields are listed is the order of the columns in the feed file.

{ /* ItemSnapshotResponse */
"items" : [
{ /* ItemSnapshot */
"itemId" : "string",
"title" : "string",
"gtin" : "string",
"brand" : "string",
"mpn" : "string",
"epid" : "string",
}
]
}
Output container/fieldTypeDescription
itemsarray of ItemSnapshotThe container for the array of items returned by the getItemSnapshotFeed method.

Note: When the value of the availability column is UNAVAILABLE, only the itemId and availability columns are populated.

Occurrence: Conditional

items.itemIdstringThe unique identifier of the eBay item.

Occurrence: Always

items.availabilityAvailabilityEnumAn enumeration value representing the item's availability (possibility of being purchased).

Values:
  • AVAILABLE
  • TEMPORARILY_UNAVAILABLE
  • UNAVAILABLE
Code so that your app gracefully handles any future changes to this list.

Occurrence: Always

items.titlestringThe seller created title of the item. This text is an escaped string when special characters are present, using the following rules:

  • Double quotes (") and backslashes (\) in the Title are escaped with a backslash (\) character
  • If there are any tabs (\t), double quotes ("), or backslashes (\) in the Title, the entire Title will be wrapped in double quotes.

For example

Before:

Misty Rainforest Modern Masters 2017 MTG Magic Fetch Land Free Ship W\Tracking

Marvel Legends HULK 8" Figure Avengers Age of Ultron Studios 6" Series

After:

"Misty Rainforest Modern Masters 2017 MTG Magic Fetch Land Free Ship W\\Tracking"

"Marvel Legends HULK 8\" Figure Avengers Age of Ultron Studios 6\" Series"

Occurrence: Conditional

items.imageUrlstringThe URL to the primary image of the item. This is the URL of the largest image available based on what the seller submitted.

Occurrence: Conditional

items.categorystringThe label of the category of the item. For example: Toys & Hobbies|Action Figures|Comic Book Heroes .

Occurrence: Conditional

items.categoryIdstringThe ID of the category of the item. For example: The ID for Toys & Hobbies|Action Figures|Comic Book Heroes is 158671.

Occurrence: Conditional

items.buyingOptionsstringA comma separated list of the purchase options available for the item, such as FIXED_PRICE, AUCTION.

Code so that your app gracefully handles any future changes to this list. Note: This column can contain multiple values.

Occurrence: Conditional

items.sellerUsernamestringThe seller's eBay user name.

Occurrence: Conditional

items.sellerFeedbackPercentagestringThe percentage of the seller's total positive feedback.

Occurrence: Conditional

items.sellerFeedbackScorestringThe feedback score of the seller. This value is based on the ratings from eBay members that bought items from this seller.

Occurrence: Conditional

items.gtinstringThe unique Global Trade Item Number of the item as defined by http://www.gtin.info. This can be a UPC (Universal Product Code), EAN (European Article Number), or an ISBN (International Standard Book Number) value.

Occurrence: Conditional

items.brandstringThe name brand of the item, such as Nike, Apple, etc.

Occurrence: Conditional

items.mpnstringThe manufacturer part number, which is a number that is used in combination with brand to identify a product.

Occurrence: Conditional

items.epidstringThe eBay product identifier of a product from the eBay product catalog. You can use this value in the Browse API search method to retrieve items for this product and in the Marketing API methods to retrieve 'also viewed' and 'also bought' products to encourage up-selling and cross-selling.

Occurrence: Conditional

items.conditionIdstringThe identifier of the condition of the item. For example, 1000 is the identifier for NEW. For a list of condition names and IDs, see Item Condition IDs and Names.

Code so that your app gracefully handles any future changes to this list.

Occurrence: Conditional

items.conditionstringThe text describing the condition of the item, such as New or Used. For a list of condition names, see Item Condition IDs and Names.

Code so that your app gracefully handles any future changes to this list.

Occurrence: Conditional

items.priceValuestringThe price of the item. Note: This price can be a discounted price.

Occurrence: Conditional

items.priceCurrencyCurrencyCodeEnumThe currency used for the price of the item. Generally, this is the currency used by the country of the eBay site offering the item.

Occurrence: Conditional

items.primaryItemGroupIdstringThe unique identifier for the item group that contains this item. An item group is an item that has various aspect differences, such as color, size, storage capacity, etc.

Occurrence: Conditional

items.primaryItemGroupTypestringThe item group type. Supported value: SELLER_DEFINED_VARIATIONS, indicates that the item group was created by the seller.

Code so that your app gracefully handles any future changes to this list.

Occurrence: Conditional

items.itemEndDatestringA timestamp indicating when the item's sale period will end based on its start date and duration. For Good 'Til Cancelled items, no value is returned in this column.

Format: UTC (yyyy-MM-ddThh:mm:ss.sssZ).

Occurrence: Conditional

items.sellerItemRevisionstringAn identifier generated/incremented when a seller revises the item. There are two types of item revisions; seller changes, such as changing the title and eBay system changes, such as changing the quantity when an item is purchased. This ID is changed only when the seller makes a change to the item.

Occurrence: Conditional

items.itemLocationCountrystringThe country where the item is physically located.

Occurrence: Conditional

items.localizedAspectsstringA semicolon separated list of the name/value pairs for the aspects of the item, which are BASE64 encoded. The aspect label is separated by a pipe (|), the aspect name and value are separated by a colon (:) and the name/value pairs are separated by a semicolon (;).

Example without Label

   Encoded Format:
   encodedName:encodedValue;encodedName:encodedValue;encodedName:encodedValue

   Encoded Example (The delimiters are empathized):
   U2l6ZQ==:WEw=;Q29sb3I=:UmVk;U2xlZXZlcw==:TG9uZw==

   Decoded:
   Size:XL;Color:Red;Sleeves:Long


Example with Label

   Encoded Format:
   encodedLabel|encodedName:encodedValue;encodedName:encodedValue;encodedLabel|

   Encoded Example (The delimiters are empathized):
   UHJvZHVjdCBJZGVudGlmaWVycw==|R1RJTg==:MDE5MDE5ODA2NjYzMw==;QlJBTkQ=:QXBwbGU=;UHJvZHVjdCBLZXkgRmVhdHVyZXM=|TW9kZWw=:aVBob25lIDc=

   Decoded:
   Product Identifiers|GTIN:0190198066633;BRAND:Apple;Product Key Features|Model:iPhone 7

Note: The separators ( | : ; ) are not encoded. You must decode each label, name, and value separately. You cannot decode the entire string.

For more information, see Encoded Aspects in the Buying Integration Guide.

Occurrence: Conditional

items.sellerTrustLevelSellerTrustLevelEnumAn enumeration value representing the eBay status of the seller.

Code so that your app gracefully handles any future changes to this list.

Occurrence: Conditional

items.imageAlteringProhibitedbooleanA boolean that indicates whether the images can be altered. If the value is true, you cannot modify the image.

Note: Due to image licensing agreements and other legal concerns, modification (including resizing) of some images is strictly prohibited. These images are for display as-is only.

Occurrence: Conditional

items.estimatedAvailableQuantityintegerThe estimated number of this item that are available for purchase. Because the quantity of an item can change several times within a second, it is impossible to return the exact quantity. So instead of returning quantity, the estimated availability of the item is returned.

Occurrence: Conditional

items.availabilityThresholdTypeAvailabilityThresholdEnum This column has a value only when the seller sets their Display Item Quantity preference to Display "More than 10 available" in your listing (if applicable). The value of this column will be MORE_THAN. This indicates that the seller has more than the 'Display Item Quantity', which is 10, in stock for this item.

The following are the Display Item Quantity preferences the seller can set.
  • Display "More than 10 available" in your listing (if applicable)
    If the seller enables this preference, this column will have a value as long as there are more than 10 of this item in inventory. If the quantity is equal to 10 or drops below 10, this column will be null and the estimated quantity of the item is returned in the estimatedAvailableQuantity column.
  • Display the exact quantity in your items
    If the seller enables this preference, the availabilityThresholdType and availabilityThreshold columns will be null and the estimated quantity of the item is returned in the estimatedAvailableQuantity column.

    Note: Because the quantity of an item can change several times within a second, it is impossible to return the exact quantity.

Code so that your app gracefully handles any future changes to these preferences.

Occurrence: Conditional

items.availabilityThresholdintegerThis column has a value only when the seller sets their 'display item quantity' preference to Display "More than 10 available" in your listing (if applicable). The value of this column will be "10", which is the threshold value.

Code so that your app gracefully handles any future changes to this value.

Occurrence: Conditional

items.itemSnapshotDatestringThis timestamp denotes the date and time the changes for that item were picked up and added to the snapshot feed file.

For example, let's say you have a snapshot feed file and also ran the getItem method. When you compare the same item information from the two sources, you see that the price in the getItem method response is different from the price in the snapshot feed file. By knowing the date and time you submitted the getItem method, you can use the itemSnapshotDate data to determine which price is the most current for this item.

Occurrence: Conditional

items.originalPriceValuestringThe original selling price of the item. This lets you surface a strikethrough price for the item.

Occurrence: Conditional

items.originalPriceCurrencyCurrencyCodeEnumThe currency of the originalPriceValue of the item and the discountAmount.

Occurrence: Conditional

items.discountAmountstringThe calculated amount of the discount (originalPriceValue - priceValue). For example, if originalPriceValue is 70 and priceValue is 56, this value would be 14.

Note: The currency shown in originalPriceCurrency is used for both discountAmount and originalPriceCurrency.

Occurrence: Conditional

items.discountPercentagestringThe calculated discount percentage. For example, if originalPriceValue is 70 and discountAmount is 14, this value will be 20.

Occurrence: Conditional

items.returnsAcceptedbooleanIndicates whether the seller accepts returns for the item.

Occurrence: Conditional

items.returnPeriodValueintegerThe amount of time the buyer has to return the item after the purchase date. This can be the number of years, months, or days depending on returnPeriodUnit. For example, if this value is '30', and the returnPeriodUnit value is 'DAY', the return period is 30 days.

Occurrence: Conditional

items.returnPeriodUnitTimeDurationUnitEnumAn enumeration value representing the period of time being used to measure the duration, such as business days or months, or years.

See the TimeDurationUnitEnum type for a list of possible time-measuring units.

Occurrence: Conditional

items.refundMethodRefundMethodEnumAn enumeration value representing how a buyer is refunded when an item is returned.

Code so that your app gracefully handles any future changes to this list.

Occurrence: Conditional

items.returnMethodReturnMethodEnumAn enumeration value that indicates the alternative methods for a full refund when an item is returned. This column will have data if the seller offers the buyer an item replacement or exchange instead of a monetary refund.

Occurrence: Conditional

items.returnShippingCostPayerReturnShippingCostPayerEnumAn enumeration value that indicates the party responsible for the return shipping costs when an item is returned.

Valid Values: BUYER or SELLER
Code so that your app gracefully handles any future changes to this list.

Occurrence: Conditional

items.energyEfficiencyClassstringIndicates the European energy efficiency rating (EEK) of the item. This field is returned only if the seller specified the energy efficiency rating. The rating is a set of energy efficiency classes from A to G, where 'A' is the most energy efficient and 'G' is the least efficient. This rating helps buyers choose between various models.

To retrieve the manufacturer's specifications for this item, when they are available, use the getItem method in the Browse API. The information is returned in the productFicheWebUrl field.

Occurrence: Conditional

items.additionalImageUrlsstringA pipe separated (|) list of URLs for the additional images of the item. These images are in addition to the primary image, which is returned in the imageUrl column. Note: This column can contain multiple values.

Occurrence: Conditional

items.deliveryOptionsDeliveryOptionsEnumA comma separated list of delivery options for the item, such as SHIP_TO_HOME and SELLER_ARRANGED_LOCAL_PICKUP. This column lets you filter out items that cannot be shipped to the buyer.

Code so that your app gracefully handles any future changes to this list.

Occurrence: Conditional

items.shipToIncludedRegionsstringA pipe (|) separated alphabetical list of the geographic countries and regions where the seller will ship the item. If a region is specified, you will need to subtract any countries and regions returned in the shipToExcludedRegions column to fully understand where the seller will ship. The COUNTRY: list is separated from the REGION: list with a semicolon (;).

Format Example:
COUNTRY:US|BM|GL|MX|PM;REGION:AFRICA|ASIA|CENTRAL_AMERICA_AND_CARIBBEAN|EUROPE|MIDDLE_EAST|OCEANIA|SOUTH_AMERICA|SOUTHEAST_ASIA;

Country Values: The two-letter ISO 3166 standard code of the country.

Region Values: AFRICA, AMERICAS, ANTARCTIC, ARCTIC, ASIA, AUSTRALIA, CENTRAL_AMERICA_AND_CARIBBEAN, EUROPE, EURO_UNION, GREATER_CHINA, MIDDLE_EAST, NORTH_AMERICA, OCEANIA, REST_OF_ASIA, SOUTHEAST_ASIA, SOUTH_AMERICA, WORLDWIDE

Code so that your app gracefully handles any future changes to this list.

Occurrence: Conditional

items.shipToExcludedRegionsstringA pipe (|) separated alphabetical list of the geographic countries and regions where the item cannot be shipped. These countries and regions refine (restrict) the shipToIncludedRegions list. The COUNTRY: list is separated from the REGION: list with a semicolon (;).

Format Example:
COUNTRY:US|BM|GL|MX|PM;REGION:AFRICA|ASIA|CENTRAL_AMERICA_AND_CARIBBEAN|EUROPE|MIDDLE_EAST|OCEANIA|SOUTH_AMERICA|SOUTHEAST_ASIA;

Country Values: The two-letter ISO 3166 standard code of the country.

Region Values: AFRICA, AMERICAS, ANTARCTIC, ARCTIC, ASIA, AUSTRALIA, CENTRAL_AMERICA_AND_CARIBBEAN, EUROPE, EURO_UNION, GREATER_CHINA, MIDDLE_EAST, NORTH_AMERICA, OCEANIA, REST_OF_ASIA, SOUTHEAST_ASIA, SOUTH_AMERICA, WORLDWIDE

Code so that your app gracefully handles any future changes to this list.

Occurrence: Conditional

items.acceptedPaymentMethodsstringIndicates the credit card service that will be used to process the transaction.
  • If this column contains PAYPAL, you can use the Buy Order API to checkout and purchase the item.
  • If this column is empty, you must use another method for checkout.

Occurrence: Conditional

items.qualifiedProgramsstringA pipe separated list of the qualified programs available for the item, such as EBAY_PLUS

Occurrence: Conditional

items.lotSizeintegerThe number of items in a lot. In other words, a lot size is the number of items that are being sold together.

A lot is a set of two or more items included in a single listing that must be purchased together in a single order line item. All the items in the lot are the same but there can be multiple items in a single lot, such as the package of batteries shown in the example below.

For example:

Item Lot Definition Lot Size
A package of 24 AA batteries A box of 10 packages 10
A P235/75-15 Goodyear tire 4 tires 4
Fashion Jewelry Rings Package of 100 assorted rings 100


Note: Lots are not supported in all categories.

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.

StatusMeaning
200Success
204No Content
This code is returned when there are no items that meet the criteria for this feed file. See Feed File Filters for details.
206Partial Content
400Bad request
404Not found
416Range not satisfiable
500Internal server error

Error codes

For more on errors, plus the codes of other common errors, see Handling errors.

CodeDomainCategoryMeaning
13000API_FEEDREQUESTThe request contains data that is invalid. Correct the request and submit the call again. For help, see the API Reference documentation for this call.
13004API_FEEDREQUESTThe 'category_id' {category_id} submitted is invalid. See the API documentation for help on how to find category IDs.
13006API_FEEDAPPLICATIONThere was a problem with an eBay internal system or process. Wait a few minutes and retry the call. If that doesn't work, contact eBay Support.
13007API_FEEDREQUESTThe feed file requested cannot be found. It is possible the file requested is in the process of being generated. Either change the date or try the call again later.
13010API_FEEDREQUESTThe mandatory 'category_id' query parameter is missing.
13012API_FEEDREQUESTThe marketplace Id {marketplaceId} is invalid. Valid values: {allowedMarketplaces}
13013API_FEEDREQUESTThe mandatory 'X-EBAY-C-MARKETPLACE-ID' header is missing. Valid values: {allowedMarketplaces}
13014API_FEEDREQUESTThe marketplace Id {marketplaceId} is not supported. Valid values: {allowedMarketplaces}
13015API_FEEDREQUESTThe mandatory 'Range' request header is missing. For help, see the API Reference documentation for this call.
13016API_FEEDREQUESTThe 'Range' request header format is invalid. Format: 'bytes=start position-end position'. For help, see the API Reference documentation for this call.
13017API_FEEDREQUESTThe 'Range' header is invalid. Please verify that the start and end positions are correct. For help, see the API Reference documentation for this call.
13018API_FEEDREQUESTThe start position in the range header is invalid.
13019API_FEEDREQUESTThe end position in the range header is invalid.
13020API_FEEDREQUESTThe mandatory 'snapshot_date' query parameter is missing.
13021API_FEEDREQUESTThe 'snapshot_date' query parameter is invalid.Valid format is 'yyyy-MM-ddTHH:mm:ss'
13022API_FEEDREQUESTThe 'category_id' {category_id} submitted is not supported.

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: Download an Hourly Changed Item Feed File

This sample returns a GZIP file with the items that have changed on August 30, 2018 between 8-9am UTC in the Cameras & Photo category. In this example, the size of the file being returned is 142MB (148897792 bytes) and the request Range header specifies to return the first 10MB (10485760 bytes).

Input

The inputs are category_id, and snapshot_date in UTC format (yyyy-MM-ddThh:mm:ss.sssZ) based on GMT, URI parameters.

The request parameters are: Range bytes=0-10485760 and X-EBAY-C-MARKETPLACE-ID EBAY_US. For more information about using these headers, see HTTP request headers.
GET
https://api.ebay.com/buy/feed/v1_beta/item_snapshot?category_id=625&snapshot_date=2018-08-30T08:00:00.000z

Output

If the call is successful, the portion of the file specified by the Range header, is returned. The call returns a 206 HTTP status and the Content-range bytes=0-10485760/148897792 response header.