Feed API beta

eBay has over a billion listings, providing you with a rich inventory that you can surface in your app or on your site. To get these items, you can use the Feed API to mirror an eBay category by downloading a TSV_GZIP file of the items in top-level (L1) categories for a specific marketplace. You can then curate the items to fit your buyers and sync the item details with the live site all off-line, and then store the items in your database.

Feed API methods overview

The Feed API has the following methods:

• getItemFeed method (or use the open source Feed SDK)
  • Retrieves the weekly Item Bootstrap feed file containing all the Good 'Til Canceled items in a specific category and marketplace.
    (feed_scope = ALL_ACTIVE)
  • Retrieves a daily Item feed file containing all the newly listed items for a specific category, date, and marketplace.
    (feed_scope = NEWLY_LISTED)
• getItemGroupFeed method
  
  • Retrieves the weekly Item Group Bootstrap feed file containing the item group variation information (aspect differences, such as color, size, storage capacity, etc.) for items in the corresponding weekly Item Bootstrap feed file.
    (feed_scope = ALL_ACTIVE)
  • Retrieves the daily Item Group feed file containing the item group variation information (aspect differences, such as color, size, storage capacity, etc.) for items in the corresponding daily Item feed file.
    (feed_scope = NEWLY_LISTED)
• getItemSnapshotFeed method
  •  Retrieves an hourly feed file containing the items that have changed within the hour/day/category/marketplace specified. You use this file to update the information of the stored items. The following is a list of the changes that are captured:
    • Title, Price, or Quantity change
    • Item ended by seller or admin
    • Item end date change
    • Add or remove a variation
    • Item created within the specified hour
• getItemPriorityFeed method
  
  • Retrieves the daily Priority Listing feed file which you can use to track the status of your priority listings within specified campaigns; e.g., added to a campaign or removed from a campaign.

Feed file filters

The items in the various feed files have been filtered to help ensure a good user experience. The following table shows the filters that are applied to each feed file.

Daily Feeds (NEWLY_LISTED)	Weekly Bootstrap Feed (ALL_ACTIVE)	Hourly Snapshot Feed	Daily Item Priority Feed
Items listed on a specific day, in a specific category Fixed price (Buy It Now); no auctions Item conditions: New (ID 1000) New Other (ID 1500) Certified - Refurbished (ID 2000) Excellent - Refurbished (ID 2010)* Very Good - Refurbished (ID 2020)* Good - Refurbished (ID 2030)* Seller Refurbished (ID 2500)** LIKE_NEW (ID 2750)*** Used (ID 3000) VERY_GOOD (ID 4000)**** eBay Top Rated and Above Standard	All items in a specific category Fixed price (Buy It Now); no auctions Item conditions: New (ID 1000) New Other (ID 1500) Certified - Refurbished (ID 2000) Excellent - Refurbished (ID 2010)* Very Good - Refurbished (ID 2020)* Good - Refurbished (ID 2030)* Seller Refurbished (ID 2500)** LIKE_NEW (ID 2750)*** Used (ID 3000) VERY_GOOD (ID 4000)**** eBay Top Rated and Above Standard	Any active item that was updated within a specific day, hour, and category Fixed price (Buy It Now); no auctions	Items in a specific category and campaign that are added or removed from the campaign or whose tracking payload has been refreshed Fixed price (Buy It Now); no auctions Item conditions: New (ID 1000) New Other (ID 1500) Certified - Refurbished (ID 2000) Excellent - Refurbished (ID 2010)* Very Good - Refurbished (ID 2020)* Good - Refurbished (ID 2030)* Seller Refurbished (ID 2500)** LIKE_NEW (ID 2750)*** Used (ID 3000) VERY_GOOD (ID 4000)**** eBay Top Rated and Above Standard
* This refurbished condition is only supported in a limited number of eBay marketplaces and categories, and the seller must be pre-qualified to list with this item condition. ** In some eBay marketplaces and categories, this refurbished condition is being replaced by Excellent - Refurbished, Very Good - Refurbished, or Good - Refurbished. *** When item condition ID 2750 applies to a Trading Card it indicates that the card is GRADED. **** When item condition ID 4000 applies to a Trading Card it indicates that the card is UNGRADED.

Buy APIs integration model

The following shows the integration model using the Buy APIs. This flow uses both the data feeds, for creating a rich selection of items, and other Buy APIs to retrieve real-time data and purchase items.

1. Use the open source Feed SDK to download a Item Bootstrap feed file of all the items in a category and apply an initial set of filters.
2. Curate the items for your business.
3. Use the Browse API to retrieve the latest item details.
4. Import the curated items into your database.
5. Update your inventory:
   • Use the hourly snapshot feed file (getItemSnapshotFeed method) and daily priority item feed () to synchronize the details of the items in your inventory with the eBay marketplace.
   • Use the open source Feed SDK to download a daily Item feed file of all the new listings in a category. Curate these new items and add them to your database.
6. Create a browse experience with these item for buyers.
7. Use the Order API to let buyers pay for the items in your app or on your site.
8. Use the Order API to purchase the items from the eBay seller.

Feed API integration

The basic steps to integrate with the Feed API and keep the items in sync with the eBay site are:

1. Get the eBay categories of a marketplace
2. Get the items
3. Curate the items offline
4. Store the eBay items
5. Sync the items with eBay
6. Get newly listed items

Get the eBay categories of a marketplace

The Feed API methods require an eBay L1 (top-level) category ID. You can use the Taxonomy API to get the L1 and leaf (child) categories for a specific eBay marketplace. This enables you to download items from a specific category, map the eBay categories to your categories, and use the leaf categories to curate the items.

eBay’s product category tree consists of the following elements that can be used for qualitative matching:

• categoryTreeId - identifies the respective marketplace
• categoryTreeVersion - identifies the current version and determines if you’ll have to update the matching
• categoryId - a unique id that identifies a certain product category in the category hierarchy for a given marketplace
• categoryName - name of the respective category
• categoryTreeNodeLevel - category level within the complete category tree
• leafCategoryTreeNode - indicates if the respective category is located on the leaf level of the category tree

To get the categories for the eBay US marketplace, do the following.

1. Get the category tree ID for a specific eBay marketplace.

   The following returns the ID for the US marketplace.

   Request:

   /commerce/taxonomy/v1/get_default_category_tree_id?marketplace_id=EBAY_US

   Response:

   "categoryTreeId": "0","categoryTreeVersion": "119"

2. Get the category tree for the eBay US site.

   Request:

   /commerce/taxonomy/v1/category_tree/0

   Response: A file containing the complete category tree for the US.

   Save this response for future use.

   Note: There are times when eBay updates categories. When this happens, run this call and update the stored category data.

You can use the data from the getCategoryTree call to find the L1 and child categories you want to use to curate the items.

In the following examples, we use items from the Sporting Goods (ID 888) - Outdoor Sports (ID 159043) - Camping & Hiking (ID 16034) category.

Get the items

This process starts by downloading the Item Bootstrap feed file for a specific category/marketplace. The Feed SDK GetFeedResponse.filePath specifies where the file will be saved. The filename of the bootstrap file indicates the category, the date the file was generated, and the marketplace used. For example:

item_bootstrap-11116-20180708-EBAY_US

Bootstrap files are generated every Tuesday and the file is available on Wednesday. However, the exact time the file is available can vary so we recommend you download the Bootstrap file on Thursday. The items in the file are the items that were in the specified category on Sunday.

To get all the items available, you need to get the Daily feed files for the missing days between the date you downloaded the Bootstrap file and the date of that file, which is returned in the Last-Modified response Header. For example, if you downloaded the Bootstrap file on Friday, you need the daily files for the previous Monday, Tuesday, Wednesday, and Thursday.

1. Use the open source Feed SDK or the getItemFeed method (-scope ALL_ACTIVE and category ID 888) to apply an initial set of filters, and download a bootstrap feed file of all the items in the L1 Sporting Goods category.

   The category of interest in this example is Camping & Hiking (ID 16034). The Feed SDK supports filtering by several item details, and by L2 and L3 categories. So one of the filters would be the 16034 category. This will greatly reduce the size of the bootstrap file. For an example see, Using config file driven approach.

2. Save the items and store the bootstrap date, returned in the Last-Modified response Header, with each item. This date tells you the "as of" date for the item details.
3. For each missing day between the current date and the date of the bootstrap file, use the Feed SDK or the getItemFeed method (-scope NEWLY_LISTED) with the same L1 category and applying the same filters to get items that have been added to eBay since the date of the bootstrap file.
4. For each daily file, save the items and the "as of" date retuned in the Last-Modified response Header.

Curate the items offline

Most partners apply complex curation criteria to the items returned in the feed file. This curation is in addition to the filtering provided by the Feed SDK. The following shows an example of the filter-funnel curation approach. This approach applies criteria in phases.

1. It starts with filtering the entire list of items by leaf categories, such as L4 categories.
2. Then filter on where you can ship to (shipToExcluedRegion and shipToIncludedRegion) and where the item is located (itemLocationCountry)
3. Then filter on the item/product aspects, such as brand or capacity, that you want to surface (various fields).
4. Then filter on other item attributes specific to your business (various fields).
5. And finally, for each item, make a real-time Browse API getItem call to:

   • Retrieve and save the latest item details and add data that is not included in the feed file, such shipping cost, the affiliate view item link (itemAffiliateWebUrl), which is used for tracking link, the postal code of the item's location, if the item can be bought using eBay guest checkout (enabledForGuestCheckout), if the item is still available (itemEndDate) etc.

     Note: eBay Partner Network, in order to be commissioned for your sales, you must use the URL returned in the itemAffiliateWebUrl field to forward your buyer to the ebay.com site.

   • Retrieve and save the Date response header value.

     The date represents the "as of" date for the item details. This date is used when syncing the item with the site.

6. Store the curated items along with the latest information retrieved by the getItem call.

   Note: For accuracy, pass in the ship-to postal (zip) code and country of the buyer in the X-EBAY-C-ENDUSERCTX request header.

Store the eBay items

After you have curated the eBay items, you need to store them. This often means needing to match eBay items with your own taxonomy. It’s highly recommended that you implement a product category matching process as described in Get the eBay categories of a marketplace section.

To fit an item into your taxonomy, you’ll have to match eBay’s current category tree structure, starting with the root (L1) categories, through as many levels as possible. Every item provided by the Feed API provides the item’s leaf category ID, which can be matched between L2 and Ln.

This approach allows you to augment your product catalog independently of the availability of generic product identifiers, like GTIN or Brand/MPN. But it also helps to strengthen a product identifier based matching process, as the combination of category and product ID can help to identify false-positive matchings. For more information, see the Taxonomy overview.

After you have matched the eBay items with your taxonomy, store the curated items along with the latest information retrieved by the getItem call performed in the Curate the items offline section.

Sync the items with eBay

After you have the eBay items stored, you will want to keep the items synchronize with the eBay site. You can use the hourly snapshot file to retrieve the items that have changed within the hour.

1. Every hour, call getItemSnapshotFeed.
2. For each item ID returned in the snapshot file, do one of the following:
   • If the item ID exists in your inventory, compare the Last_Modified date returned by the getItemSnapshotFeed method with the stored (as of) date for the item. If the Last_Modified is later than the (as of) date of the item in the inventory, update all the details of the item including the (as of) date.
   • If the item ID does not exist, skip it and go to the next item.

Get newly listed items

Each day, do the following:

1. Use the Feed SDK (-scope NEWLY_LISTED) to get the newly listed items from the day before. Save both the item details and the date value.
2. Curate the items returned.
3. Add the items to your inventory.

Motivate buyers to purchase

You can use the Marketing API to enhance and encourage conversion for the items you surface by showing buyer's the best selling products, products that were also bought and also viewed, and product review ratings related to the item.

For examples, see the Marketing API in the Buy Integration Guide.

Retrieve a gzip feed file

The TSV_GZIP feed files, which are binary, can be streamed in chunks. You must specify the size of each chunk in bytes using the request Range header.

The maximum number of bytes you can request is 100 MB, which is 104857600 bytes. When you specify the Range header, the content-range response header is returned showing rangeValueSpecified/totalSizeOfFile.

In the following example, the request Range header is set to retrieve the maximum number of bytes. The content-range response shows that the total size of the file is 1076602 bytes. This means the entire feed file was retrieved. The HTTP status code will be 200 OK.

Range bytes=0-104857600

content-range 0-104857600/1076602

If the size of the feed file is greater than 104857600 bytes, it will take multiple methods to retrieve the entire file. This is discussed in the next section.

How to retrieve a feed file using multiple calls

When retrieving a feed file in chunks, it is important to remember that the response is for a certain number of bytes not records. This means you must combine the chunks in the correct order. Also note that the chunks are binary not human readable. Because you are retrieving the file in pieces, if one method fails, you do not have to start over, you can just resubmit that call.

To retrieve a file that is 24MB (25165824 bytes), you would make 3 calls, which can be multi-threaded. Each call will return a gzip file containing the number of bytes specified by the Range request header. These will be binary files and must be put together in the correct order to get the entire feed file.

The table below shows the value of the Range request header, the HTTP response status, and the Content-range response header for each call. The HTTP status code for a successful call is always 206, even for the last call, because the response is never the entire file.

	Range Request Header	HTTP Response Status	Content-range Response Header
First method	Range: bytes=0-10485760	206 (successful partial response)	0-10485760/25165824
Second method	Range: bytes=10485761-20971520	206 (successful partial response)	10485761-20971520/25165824
Third method	Range: bytes=20971521-31457280	206 (successful partial response)	20971521-31457280/25165824

If the Range value is invalid, a 416 HTTP status code is returned and the content-range header returns */totalSizeOfFileValue.

Understand encoded aspects

The Feed API returns aspects for products and items. Aspects are the variations of a product or item, such and size and color, or brand and model. Aspects can be just name/value pairs or groups of name value pairs.

For Example

Name/Value Pairs	Groups of Name/Value Pairs

The value for the label, name, and value are often created by the seller when listing the item on the site. There are no restrictions or reserved characters for these. This means that there aren't any characters the service could use as delimiters that are guaranteed not to be in one of these values.

For example, look at the first example above (Name/Value Pairs). Notice that all the "name values" include a colon (Style:). If the service used a colon ( : ) between the name and value pair, it would return Style::, which would cause problems for determining the name/value pairs that follow. To solve this issue, the values of the label, name, and value are BASE64 encoded. The delimiter for a label is a pipe ( | ), the delimiter between the name and value is a colon ( : ) and the delimiter between name/value pairs is a semicolon ( ; ).

Name/value pair example

encodedName:encodedValue;encodedName:encodedValue;

Label name/value pair example

encodedLabel|encodedName:encodedValue;encodedName:encodedValue;encodedLabel|encodedName:encodedValue;

Decoding aspects

As noted above, the text of the label, name, and value is BASE64 encoded. The following is what would be return in the localizedAspects field for the first example of name/value pairs above.

U3R5bGU6:QnV0dG9uLUZyb250;U2l6ZSBUeXBlOg==:QmlnICYgVGFsbA==;U2l6ZSAoTWVuJ3MpOg==:TQ==;

Decoded: Style::Button-Front;Size Type::Big & Tall;Size (Men's)::M

But remember, the separators ( | : ; ) are not encoded, so you cannot decode the entire string at one time. You must decode each value separately.

U3R5bGU6 = Style:
QnV0dG9uLUZyb250 = Button-Front

You can find a BASE64 decoder at https://www.base64decode.org.