API Basics

Introduction

The Etsy API provides a simple RESTful interface with lightweight JSON-formatted responses to use many of Etsy's website features, including public profiles, shops, listings, tags, favorites, and sales data, using OAuth to allow both read and write access to users' public and private data. This document provides information to developers on how to integrate with the Etsy API.

Accessing the API

The Etsy API accessed under the openapi subdomain. A sample unauthenticated request might look like:

GET https://openapi.etsy.com/v2/listings/active?api_key={YOUR_API_KEY}

To retrieve the most recent active listings on Etsy.

API requests must use HTTPS, HTTP requests will result in 400 Bad Request responses.

Authentication

The Etsy API requires an application key that is provided during app registration. The key identifies your application to the Etsy web service, and is used to track overall call usage. It's passed using the standard api_key parameter.

For write access and for accessing private user data, an OAuth access token is required. Your application key is required to start the OAuth authentication process.

New users register an application and receive a personal access API key upon signup. These keys have full access to resources in the Etsy API, however they are restricted to allow authentication only for the user who registered the application.

Rate Limiting

Using public (api key-based) authentication, clients are allowed 10,000 requests per 24-hour period, with a limit of 10 queries per second. We use a progressive rate limit structure, where a 24 hour period is chunked into 12 two-hour blocks. Rate limits are calculated by summing the number of requests made per two-hour block over the past 24 hours. This is to maximize your use of the API - for example, if you hit a rate limit, you'll only need to wait for at most two more hours in order to get a few more allowed requests (the exact amount will depend on the number of requests you made in the two-hour block of 24 hours prior). Using private (OAuth) authentication, clients are given the same limits per OAuth access token.

If your application needs more than the allotted number of calls, contact us at developer@etsy.com with a description of the application and an estimate on needed call usage. You might also want to investigate the use of caching to keep the number of calls to a minimum, and make your application more responsive.

Headers: Every API response bears rate limit headers, as described below:

X-RateLimit-Limit: 10000
X-RateLimit-Remaining: 9924

These default rate limits are subject to change at any time, without notice.

API Requests

The Etsy API uses a RESTful calling style that works with standard HTTP calls. Any web programming language (PHP, Ruby, Perl, Python, Java, Objective C, C#...) should be able to make and receive HTTP networking calls; consult the documentation for your language of choice.

Request URLs

In a RESTful API, each resource or collection of resources is identified by a unique URL, such as:

https://openapi.etsy.com/v2/listings/:listing_id

The prefix v2 is the version specifier and must be present. When significant changes are made to the API (changes that would break compatibility with existing applications) this value will change.

URL paths contain the unique IDs of resources. These are identified by a leading colon, as with :listing_id above. Before making a call, you must substitute a valid ID value for these placeholders. ID parameters must appear in the URL and cannot be substituted for GET parameters. All ID parameters listed in the URL pattern must be present.

Output Formats

The Etsy API handles multiple output formats. Currently, the only supported formats are JSON and JSONP (see JSONP and JavaScript.) Output formats are selected with a specifier that is appended to the URL, like a filename extension:

Format	Specifier	Description
JSON	.json	JavaScript Object Notation
JSONP	.js	JSON with Padding

JSON is the default, and will be used if nothing is specified. Using the alternate JSONP format, the example from the previous section would look like this:

https://openapi.etsy.com/v2/listings/:listing_id.js

HTTP Methods

RESTful APIs use standard HTTP methods to denote actions against a resource:

• GET - Reads a resource. Returns HTTP 200 on success.
• POST - Creates a new resource. Returns HTTP 201 on success.
• PUT - Updates a resource. Returns HTTP 200 on success.
• DELETE - Deletes a resource. Returns HTTP 200 on success.

Because some toolkits lack support for PUT and DELETE (most notably JavaScript) you can use method overloading to fake an HTTP method. Use a GET or POST call and append the standard method parameter:

https://openapi.etsy.com/v2/users/__SELF__/favorites/listings/12345?method=DELETE

The standard token __SELF__ in the above calls maps to the user ID of user using your application under OAuth. It can be used in any URL in place of :user_id under the private entry points. When used under the public entry points, it will cause an error.

Parameter Types

Many API methods take one or more parameters, either as query parameters of the URL itself, or as POST parameters. The documentation for each method references these standard types:

Param Type	Meaning
string	Any string (up to 255 characters).
int	A whole number value.
epoch	A whole number value representing UNIX epoch time, or any string accepted by PHP's strtotime() function.
float	A number with or without a decimal point. Represented in output as a string, to avoid precision errors.
boolean	A logical true or false value. May be passed to API requests as the strings "true" or "false" or "1" and "0". In JSON output, symbolic constants are used.
user_id_or_name	Either a user's numeric ID or login name.
shop_id_or_name	Either a shop's numeric ID or login name. (Note: shop IDs are not interchangeable with user IDs.)
team_id_or_name	Either a teams's numeric ID or full name, including spaces and punctuation. (Note: Team captains may change the name of a team.)
treasury_description	A string 255 characters long or less
treasury_id	A string that uniquely identifies a treasury.
treasury_search_string	In the general case, this can be any string. However, there are four special prefixes that can be used. "shop:" will look for lists where one of the shop's listings is included. "curator:" will find all the lists created by the person specified. "title:" will find lists with a specific title. "tags:", "listing_title:", "listing_tags:" follow the same pattern. Because the colon ":" is used as a special character to separate the special prefixes, you may only have 1 colon in your search string, and the text that comes before the colon must match one of the prefixes stated above.
treasury_title	A string 127 characters long or less
enum(values)	A predefined list of string values, for example true and false. Any value not in the list will result in an error.
array(type)	A list of values, separated by commas (","). Do not include parentheses or brackets. Each value must be a valid instance of type.
map(keyType,valueType)	A JSON dictionary of key/value pairs. Each key and value must be a valid instance of keyType and valueType. E.g. {"key":"value"}
color_triplet	Either an HSV color specified as an array in the range 0;0;0 - 360;100;100, or an RGB color specified in hexadecimal notation in the range #000000 - #FFFFFF.  (RGB colors are converted to HSV internally, which may result in small rounding errors.  They may omit the leading "#", or use the three-digit form.)
color_wiggle	Specify the degree of tolerance for color matching where 0 is the most accurate, and 30 is the least.
latitude	A valid numeric latitude, between -90.0 and 90.0
longitude	A valid numeric longitude, between -180.0 and 180.0
image	An image file; see Uploading Images
region	An ISO 3166-1 alpha 2 country code. Currently supported values: US, CA, AU, GB, IN, DE, FR, NL, IT, ES, RU, PT, GR, IE, JP, NZ, PL
currency	A 3-letter ISO 4217 code.
language	An IETF language code. Currently supported values: de, en, es, fr, it, ja, nl, pl, pt, ru
category	A string ID that uniquely identifies a category path (e.g. Clothing/Men/Pants)
taxonomy	An entire taxonomy node, serialized in JSON.
listing_variation	A JSON object. See Working with Variations.
featured_rank	An int that determines the order of listings in the user's Featured Listings. Lower numbers are towards the front of the queue. 0 or __OFF__ removes the listing from the queue, and __LAST__ places the listing at the end of the queue. Note that featured ranks are reordered and normalized on the back end, so the listing's final rank may be different from the value passed in, but will be correct relative to the rest of the queue.
stringJSON	A string that contains a valid JSON object. Note that this does not indicate that the entire post body should be JSON, only that the value of this parameter should be JSON.

Standard Parameters

Here is a list of standard parameters that are accepted by many or all API methods:

Parameter	Type	Meaning
api_key	string	Your API key. Required for all public entry point calls
method	string	Used to specify a custom HTTP method for method overloading.
limit	int	Specifies the maximum number of records to return.
offset	int	Skips the first N records before returning results. Combine with limit for pagination.
fields	array(string)	Used to limit the fields in a response object; fields not listed will not be returned. Separate multiple fields with commas.
includes	array(string)	Used to include associated objects in a response. See Working with Resources section.
callback	string	Used in conjunction with the JSONP output format to specify a callback function name.

JSON Data

Data is returned using JSON, a lightweight serialization language that is compatible with many different languages. JSON is also syntactically correct JavaScript code, which means that it can be parsed with JavaScript's own eval() function.

Standard Response Format

Each API response is wrapped in a standard structure that holds the results of the API call, plus metadata about the request:

{
     "count":integer,
     "results": [
         { result object }
     ],
     "params": { parameters },
     "type":result type
}

count specifies the total number of results available for this call, which may be more than the number of results returned in this request. For example, if count is 1000, you can page through the results in blocks of 100 by specifying limit=100&offset=0, where offset is a multiple of 100 up to 900. See Pagination below.

results is an array of results. For consistency's sake, it is always an array, even if only one result is expected.

params echoes the parameters that were passed in the request.

type specifies the type of the objects in the results array. (See the individual pages under "API Reference".)

Pagination

The default records returned per call is 25, and the maximum number that can be returned is 100. We provide limit and offset parameters to allow navigation through larger data sets. Responses include a count field, which specifies the total number of records available via pagination. For performance reasons, the offset parameter is limited to a maximum value of 50000.

Here's an example of sequential requests to paginate through the most recent 300 listings, 50 at a time:

https://openapi.etsy.com/v2/listings/active?limit=50&offset=0
https://openapi.etsy.com/v2/listings/active?limit=50&offset=50
https://openapi.etsy.com/v2/listings/active?limit=50&offset=100
https://openapi.etsy.com/v2/listings/active?limit=50&offset=150
https://openapi.etsy.com/v2/listings/active?limit=50&offset=200
https://openapi.etsy.com/v2/listings/active?limit=50&offset=250

Standard Response Codes

The Etsy API uses standard HTTP status codes to indicate success or failure of API calls (Consult the documentation for your programming language to learn how the read the status code of an HTTP call)

HTTP Code	Message	Meaning	Response Body
200	OK	Success!	A JSON response (see below.)
201	Created	A new resource was successfully created.	A JSON response containing the new resource's data.
400	Bad Request	You've made an error in your request (such as passing a string for a parameter that expects a number).	An error message
403	Forbidden	You've exceeded the rate limits for your account, or the data you're trying to access is private.	An error message
404	Not Found	The requested resource could not be found, or the URI doesn't correspond to any known command.	An error message
500	Server Error	An internal error on our side. If this problem persists, submit a bug report in the bug section of our forums.	An error message
503	Service Unavailable	The Etsy API is down for scheduled maintenance; please try again later (this should be rare!)	An error message

The X-Error-Detail HTTP header will contain a detailed description of many errors.

Tip: What's the difference between a 404 Not Found and a 200 OK with empty results? If you're searching for a specific record, say listing #1234567890, and it doesn't exist, that's a 404 Not Found. The record wasn't found; it doesn't exist; it probably never did. However, if you're searching for a set of records and no listings match your search, that's a 200 OK. There's nothing wrong with your request, but it doesn't match anything, and your result set is empty.

This might seem a little arbitrary, but it makes practical sense: search engines typically don't display an error page if your search comes up empty. On the other hand, trying to access a URL that doesn't exist will turn up a standard 404 error page. Your application will probably have similar behavior.