Note: Do you still need the beta version of the Feed API? Go to the Feed API beta section.
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 GZIP file of the items in your chosen categories and specific marketplaces. You can then curate the items to fit your buyers and sync the item details with the live site—all offline—and then store the items in your database.
The Feed API has the following methods:
- getAccess method—Returns the details of the application's feed file access configuration. Lists the marketplaces and categories for which the application can download feeds.
- getFeedType method—Returns a list of the feeds of a particular feed type that are available for download. Currently CURATED_ITEM_FEED is the only available feed type.
Note: For bootstrap, item, snapshot and priority feeds, continue to use the Feed Beta API.
- getFeedTypes method—Returns a list of all the feeds available to download, listed by feed type. The response includes information on how frequently the feed is made available (DAILY, HOURLY, or WEEKLY—currently only DAILY is supported), supported feeds in in each available type, each feed's supported marketplaces and each feed file's status (ACTIVE, PAUSED, DEPRECATED).
- downloadFile method—Returns a specified GZIP feed file, as specified in the request URI. The downloaded file has detailed information on each listing in the feed file. For more information about fields that may be included in a feed file, see Feed File Fields.
- getFile method—Returns a list of the metadata for a particular available download file. It includes details on the date of its feed, its file type, the frequency with which it is made available, its format, and its marketplace.
- getFiles—Returns a list of the feed files available to download. The file search can be filtered in the URI by feed type, feed pull frequency, L1 category, and how far back in time from the present the feed can be searched for.
The basic steps to integrate with the Feed API and keep the items in sync with the eBay site are:
Use the getFeedTypes method to create a list of the feeds you can download. The list provides details about each feed type including how frequently it is made available, the marketplaces it supports (e.g., EBAY_US), and the authorization scopes needed for access (see Specifying OAuth scopes).
Note: Refer to Supported feed types for more details about the feed types supported by the Feed API.
The getFeedTypes method also gives you each feed type's feedTypeId, which you will use with the getFeedType method once you have identified a specific feed type you wish to target.
The getFeedTypes method is a simple GET call using a URI call and no input payload:
You can filter your search in the URI by providing a feed_scope parameter, so your returned list is not filled with unwanted feeds. You can also add a marketplace_ids parameter, to limit your returns to useful markeplaces. For example, the following call limits the responses to feed files whose feed scope is sell.inventory, and whose marketplace is the U.S.
Use the getFeedType method when you do not need the complete list of feeds provided by the getFeedTypes method. The getFeedType method provides the same information as the getFeedTypes, but confines the search to a specific feed type, as provided in the URI.
The refined search results in a smaller file whose data is easier to read and manipulate programatically.
When you submit an application for use with eBay, you will configure your application to allow access to a number of product categories within designated marketplaces (see Buy APIs Requirements). For instance, category 63, Comics, in the US market, EBAY_US. Before attempting to acquire a feed, it is useful to know which categories and marketplaces your application can access. The getAccess method gives you a list of those categories and marketplaces.
The getAccess method uses a simple URI call:
The response payload is a listing of the marketplaces and categories that pertain to your application, which can be used to focus a search using the getFeedType(s) and getFile(s) methods. The following is an example.
A further way to granulate your data search is to use the getFiles and getFile methods.
It is possible to download a listing of all available feeds with a simple call getFiles call with no URI parameters.
However, the real power of the getFiles method is in its URI parameters, with which you can identify the exact file you need. You can use the feed type and feed scope you identified using the getFeedType method as containing the feed you want, then further focus your call with one or more category ids. Lastly, you can use the look_back parameter to further confine your search to determine how recently you feed to have been pulled.
For example you could limit your search to curated item feeds, in cookware (categoryid of
974) that have been made available in the two days (note that the look-back value's unit is always minutes, so two days is 2880 minutes).
The final step is to download the actual GZIP file, using the downloadFile method.
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