API Documentation

Real-Time Feeds

The Etsy API now has infrastructure to support real-time updates of our data. Our first available feed is the real-time listings feed and we also now have per shop real-time listings feeds. This resource is not generally available. If you would like access, please write to developer@etsy.com.

Consuming the Real-time Listings Feed

We've set up a real-time listing feed via our RESTful API, which you can keep up with by regularly polling.

The API Key (api_key)

To access our API, you will need an api_key. An api_key is a parameter you will need to include in every request to our API. Note the key for real-time feeds is separate from the key used for the rest of the api, and each developer's key will be unique and have its own rate limits and daily call quotas.

Methods

The base URL for the feeds API endpoint is http://openapi.etsy.com/v2/feeds/. Calling the endpoint directly will list possible methods.

/listings/latest

Unlike our regular API methods, these results are not cached and regular polling will return a complete list of Listings. You can control the number of listings returned by using a time_limit (default of 10 seconds) and time_offset parameter (no default and required, units are epoch seconds). In addition, limit (default 25, max 100) and offset (default 0) parameters can be used in conjunction with the time_limit and time_offset parameters. We currently have around ~250 new listings a minute on average, though this is subject to time of day, year, and our growth, so you'll want to retrieve several times a minute to make sure you don't miss any new listings.

Listings in this feed mean there has been some sort of change to it. This may mean that the Listing underwent one of several actions: it may have been newly created, renewed, activated (left edit state), deactivated (in edit state), deleted, the user is on vacation, or removed for unspecified reasons. Only Listings with a state of active are available for sale.

The possible states for Listings in the feed are: active, sold_out, expired, removed, edit, vacation, private, unavailable. The items available for purchase have only one state: active. Any other state indicates that the item cannot currently be purchased, and you can remove it from display from your site. You may continue to link to Listing pages that are sold_out or in vacation state, but Listings in these states are not purchasable.

`state`	Meaning	Display?
`active`	The Listing is currently for sale.	Yes
`sold_out`	The Listing has sold out.	Optional
`expired`	The Listing has expired.	Optional
`vacation`	The seller is not accepting orders at this time, but will return later.	Optional
`removed`	The Listing has been removed by its owner.	No
`edit`	The Listing is currently being edited by the owner.	No
`private`	The owner of the Listing has requested that it not appear in API results.	No
`unavailable`	The Listing has been removed by Etsy admin for unspecified reasons.	No

As when parsing methods that return Listings in our regular api, you'll need to be careful that Listings in various states may expose fewer fields than items in the active state. For items in the vacation or sold_out state, all fields will be exposed, with the exception that sold_out listings will not display price. For all other states, the only guaranteed fields will be listing_id and state.

To return JSON, call this method like so: http://openapi.etsy.com/v2/feeds/listings/latest?api_key=<api_key>

To return Atom formatted data, call this method like so: http://openapi.etsy.com/v2/feeds/listings/latest.atom?api_key=<api_key>

Atom format

We also provide the option to retrieve listings in a valid, standards-compliant Atom format. It is essentially a mapping of our Listing resource fields to Atom fields, with any other fields not having a good mapping stored as XHTML inside the <content> element.

The mapping is as follows. The left column is an XPath of an element in the Atom feed, and the right column is a Resource field (described in our API documentation). X means the element does not correspond to a standard resource field and a description follows.

XPath in Atom Feed	Etsy API Equivalent	Notes
`//entry/author/name`	Listing.Shop.shop_name
`//entry/id`	Listing.listing_id
`//entry/title`	Listing.title
`//entry/updated`	n/a	Time that this feed is retrieved (this is because many feeds do not have correct updated elements and thus many readers and parsers do not understand the updated element correctly)
`//entry/published`	Listing.original_creation_tsz
`//entry/link[0]`	Listing.url
`//entry/link[1]`	Listing.Shop.url	Equivalent to pulling via Includes in our regular API
`//entry/link[2]`	Listing.MainImage.url_75x75	Equivalent to pulling via Includes in our regular API
`//entry/link[3]`	Listing.MainImage.url_170x135	Equivalent to pulling via Includes in our regular API
`//entry/link[4]`	Listing.MainImage.url_570xN	Equivalent to pulling via Includes in our regular API
`//entry/link[5]`	Listing.MainImage.url_fullxfull	Equivalent to pulling via Includes in our regular API
`//entry/content/div/div [@class='updated']`	None	The epoch time of the update to the listing that triggered this ping. The updated element of the entry only reflects the time the ping was sent, which due to network delays, may diverge quite a bit from the true update time.
`//entry/content/div/div [@class='description']`	Listing.description
`//entry/content/div/div [@class='state']`	Listing.state
`//entry/content/div/div [@class='user_id']`	Listing.user_id
`//entry/content/div/div [@class='creation_tsz']`	Listing.creation_tsz
`//entry/content/div/div [@class='ending_tsz']`	Listing.ending_tsz
`//entry/content/div/div [@class='original_creation_tsz']`	Listing.original_creation_tsz
`//entry/content/div/div [@class='last_modified_tsz']`	Listing.last_modified_tsz
`//entry/content/div/div [@class='price']`	Listing.price
`//entry/content/div/div [@class='currency_code']`	Listing.currency_code
`//entry/content/div/div [@class='quantity']`	Listing.quantity
`//entry/content/div/div [@class='tags']`	Listing.tags	Each tag is in a separate div
`//entry/content/div/div [@class='materials']`	Listing.materials	Each material is in a separate div
`//entry/content/div/div [@class='category_path']`	Listing.category_path	Each category is in a separate div
`//entry/content/div/div [@class='shop_section_id']`	Listing.shop_section_id
`//entry/content/div/div [@class='featured_rank']`	Listing.featured_rank
`//entry/content/div/div [@class='state_tsz']`	Listing.state_tsz
`//entry/content/div/div [@class='hue']`	Listing.hue
`//entry/content/div/div [@class='saturation']`	Listing.saturation
`//entry/content/div/div [@class='brightness']`	Listing.brightness
`//entry/content/div/div [@class='is_black_and_white']`	Listing.is_black_and_white
`//entry/content/div/div [@class='non_taxable']`	Listing.non_taxable
`//entry/content/div/div [@class='views']`	Listing.views
`//entry/content/div/div [@class='origin_country_id']`	Listing.ShippingInfo.X.origin_country_id
`//entry/content/div/div [@class='origin_country_name']`	Listing.ShippingInfo.X.origin_country_name

Note that the listing descriptions, which are in entity-encoded HTML, are re-encoded before they're included in the XML. This means that HTML entities in the feed will appear to be double-encoded. You should at the very least, decode the ampersand (&) XML entity before display the listing.

As when developing any other Etsy API application, we recommend the following tools:

JSONView browser plugin to view JSON pretty-printed (Firefox and Chrome)
Firefox to view Atom feeds in a human-readable format

Your Developer Account

Looking for Etsy Apps?

Check out our new
App Gallery!

It's the best way to find cool and useful tools built upon Etsy's API.

Create Your Etsy Account