The Etsy API

Contents

  1. Introduction
  2. Concepts
    1. Authentication
    2. HTTP Requests
    3. HTTP Status Codes
    4. Rate Limiting
    5. Pagination Limiting
    6. Encoding
  3. How to Make A Request And Process The Response
    1. Sample Request from PHP
    2. Sample Response
    3. Sample Response in PHP
  4. API Request Structure
  5. Parameter Types
  6. Standard Parameters
  7. Standard Response Codes
  8. API Response Structure
  9. Using the JSONP interface with JavaScript
  10. Resource Types
    1. Users
    2. Shops
    3. Shop Sections
    4. Listings
    5. Images
    6. Gift Guides
    7. Tags
    8. Categories
    9. Feedback
    10. Methods
  11. Commands
    1. User Commands
    2. Shop Commands
    3. Listing Commands
    4. Feedback Commands
    5. Tag and Category Commands
    6. Favorites Commands
    7. Gift Guide Commands
    8. Server Commands

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 gift guides.  This document provides information to developers on how to integrate with the Etsy API.

↑ Back to top.

Concepts

Authentication

The Etsy API requires a developer key which is provided during registration.  The key identifies you as a unique entity making calls against the Etsy web service, and is used to track overall call usage.  Currently, the available API methods access public information, so there is no additional authentication needed.  (Etsy is reviewing OAuth token authentication in conjunction with the release of more API methods.)

HTTP Requests

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

HTTP Status 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.  See the section Standard Response Codes for a description of the codes used and their meaning.

Rate Limiting

Clients are allowed 5,000 requests per 24-hour period, in addition to rate limits on queries per second.  You will receive an automated email when you approach your daily limit.  If your application needs more than the allotted amount of calls, contact us at developer@etsy.com with a description of the application and an estimate on 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.)

Pagination Limiting

The default set of returned records in a call is 10, and the maximum number that can be returned is 100.  We provide count, offset and limit parameters to allow navigation through larger data sets.

Encoding

The Etsy API uses JSON, a lightweight data serialization language that is compatible with many different languages.  See here for support for your language of choice.

↑ Back to top.

How to Make A Request And Process The Response

Here's a step-by-step example of how to make a request to the Etsy API.  We'll make a request to get details for a fictional user called "testusername"  using the getUserDetails method.  If you consult the documentation for that method, you'll see something like this:

Method Name getUserDetails
Synopsis Get the details of a user.
HTTP Method GET
URI /users/{user_id}
Parameters
Name Required Default Type
user_id Y   user_id_or_name
detail_level N low enum(low, medium, high)
Return Type user

Every Etsy API request begins with the base URL:

http://beta-api.etsy.com/v1

and ends with the URI for the command.  The part of the URI that reads {user_id} is an embedded parameter—you'll need to substitute either the user name "testusername" or the ID of the profile you're trying to access.

Finally, you'll add a question mark ("?") plus any optional parameters you'd like to send (in this case, detail_level), and of course, your API key.  The final request looks like this:

http://beta-api.etsy.com/v1/users/testusername?api_key=<your_API_key>

You can test this right in your browser.  You should see a long string of JSON data language.  Note that the object returned is of resource type user.  See section Resource Types for for details on this resource.

Sample Request from PHP

Here is an example of a call in a PHP script. You can use any language that supports HTTP requests (JavaScript, Ruby, Perl...) which is just about every language in use on the web.

$url = "http://beta-api.etsy.com/v1/users/testusername?api_key=<your_API_key>";
$ch = curl_init($url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response_body = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if (intval($status) != 200) die("Error: $response_body");

Notice that in line #6 we're using the value of $response_body as an error message.  In the event of an error, the response body will contain a plaintext formatted explanation of the problem. The error will not be JSON encoded.

Sample Response

Here's the response from our request above (with added white space to make it easier to read.)  The response is formatted using JSON, a simple data serialization language that can be used by just about any language on the web.  (To find JSON support for your language, go here.)

{
    "type":"user",
    "count":1,
    "results": [
         {
           "user_name":"testusername",
           "user_id":123456,
           "url":"http:\/\/www.etsy.com\/profile.php?user_id=123456",
           "image_id":78910,
           "image_url_25x25":"http:\/\/ny-image0.etsy.com\/iusa_25x25.78910.jpg",
           "image_url_30x30":"http:\/\/ny-image0.etsy.com\/iusa_30x30.78910.jpg",
           "image_url_50x50":"http:\/\/ny-image0.etsy.com\/iusa_50x50.78910.jpg",
           "image_url_75x75":"http:\/\/ny-image0.etsy.com\/iusa_75x75.78910.jpg",
           "join_epoch":1229379928.06,
           "city":"Walla Walla, WA"
         }
    ],
    "params": {
        "user_id":123456,
        "detail_level":"low"
      },
    "type":"user"
}


Notice that in the response above, the user name "testusername" that you passed in has been helpfully converted into a user ID.  Since it's slightly more efficient to look up users by ID, we suggest that you use the ID for subsequent requests.  (The strange looking "\/" sequences are a side-effect of the JSON encoding, and will be converted to normal forward slashes when you decode the response data.)

Sample Response in PHP

And here's how we'd parse and use the response in PHP:

$response = json_decode($response_body);
$user = $response->results[0];
print $user->user_name."'s profile URL is: ".$user->url."\n";

↑ Back to top.

API Request Structure

Now that you've seen an example of an API call, here's a more in-depth rundown of the various parts of the Etsy API.

Each API request has the following components:

 

  1. Base URL - the Etsy API server and API version
  2. Command URI - the API method/command
  3. Output Format - how to encode the response data
  4. API Key - your Etsy API key
  5. Optional Params - name-value pair string of optional parameters

So for the example request:

http://beta-api.etsy.com/v1/users/testusername?api_key=<your_api_key>&detail_level=high

...the components are:

URL Component Sample Value
Base URL http://beta-api.etsy.com/v1
Command URI /users/testusername
Output Format .json
API Key ?api_key=<your_api_key>
Optional Params &detail_level=high

Notes:

  • v1 is the version number; it's required for all requests.
  • "testusername" is an embedded parameter; these are always required parameters.
  • The output format is optional; .json is the default for all requests and will be used if nothing is specified.  This document will leave it off in examples.
  • You must sign up for your own API key and specify it in place of <your_api_key>.

Tip: You might decide it's easier to deal with the embedded parameters as normal GET parameters; this is allowed for all commands. For example, the following two URLs are equivalent:

Command URI Pattern /users/{user_id}
Standard syntax http://beta-api.etsy.com/v1/users/testusername?api_key=...
Alternate syntax http://beta-api.etsy.com/v1/users?user_id=testusername&api_key=...

↑ Back to top.

Parameter Types

The Etsy API supports the following parameter types:

Param Type Meaning
string Any string (up to 255 characters).
int A whole number value.
float A number with or without a decimal point.
user_id_or_name Either a user's numeric ID or login name.
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(int) A list of integers, with values separated by semicolons (";").  (Do not include parentheses or brackets.)
array(string) A list of strings, with values separated by semicolons
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.)

In addition, the following additional types may appear in JSON return data:

Param Type Meaning
string Any string (up to 64k characters).
boolean In JavaScript, one of the predefined constants true or false. (Your language may have its own rules for interpreting boolean values in JSON data.)

↑ Back to top.

Standard Parameters

The following parameters are accepted by many or all commands, and always have the same meaning when used:

Parameter Type Required Default Value Use
api_key string Y none Authorizes the request. You will need to sign up for a key here.
limit integer N 10 The number of results to return.  The maximum number returned in any API call is 100.
offset integer N 0 Skip this many results from the beginning of the list. Combine with limit to page through large result sets
detail_level enum(low, medium, high) N low

How much data to return in each result; see Resource Types for an explanation of the fields returned for each.

↑ Back to top.

Standard Response Codes

The Etsy API uses standard HTTP response codes to indicate success or error.  Here are the error codes that you're most likely to encounter:

HTTP Code Message Meaning Response Body
200 OK Success! A JSON response (see below.)
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

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.

↑ Back to top.

API Response Structure

When a call returns a successful response, the data returned is in JSON format.  For an explanation of this structure, visit the JSON website.

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

Notes:

  • A successful response will always be an object with these fields: count, results, params, and type.
  • count - total number of results available for this request. It may be higher than the number of results returned. (Use offset and limit to page through all the results.)
  • results - array of objects (See Resource Types for details of the result types.)
    • If the request is a search, and no matches were found, results will be an empty array and count will be zero.
  • params - map of all parameters that were passed into the command, plus whatever default values were applied for remaining parameter names. It gives context to the response and can be used to reconstruct the original response.
  • type - the type of result: user, shop, listing, tag, gift-guide or method.  See Resource Types for more information.

↑ Back to top.

Using the JSONP interface with JavaScript

JavaScript programmers will be familiar with the Same-Origin Policy, which limits requests made with the XMLHttpRequest object to servers on the same domain name as the page running the JavaScript code.  For this reason, you won't be able to call the Etsy API directly using XMLHttpRequest.  One way to get around this limitation is to build a proxy application to make requests to beta-api.etsy.com and serve the response to your JavaScript code.  This can be useful if you want to implement caching.  Another solution is to use the Etsy API's built-in JSONP interface, which uses <script> tag injection as an alternative to XMLHttpRequest.  (For an in-depth description of JSONP, see here.) To use the JSONP interface, you will need to make some small changes to the way you call and process the Etsy API:

  • The URI must end in .js
  • An additional parameter, callback, must be specified
  • Callback values may only contain the letters A-Z, the digits 0-9, periods ("."), underscores ("_") and square brackets ("[" and "]").

Here's an example of an API method, first called using the standard JSON interface, and then with the alternate JSONP interface:

JSON Interface http://beta-api.etsy.com/v1/users/testusername?api_key=<your_api_key>
JSONP Interface http://beta-api.etsy.com/v1/users/testusername.js?callback=getData&api_key=<your_api_key>

To call this request, you would first define a JavaScript function getData() to process the response, and then insert a <script> tag to make the request, like so:

<script type="application/javascript">
function getData(data) {
      if (data.ok) {
            // do something with the data here
        } else {
            alert(data.error);
      }
}
</script>

<script src="http://beta-api.etsy.com/v1/users/testusername.js?callback=getData&api_key=<your_api_key>"></script>

Notice that we need to explicitly check the value of data.ok before proceeding with the getData() function.  This is because the normal error handling rules of the Etsy API don't apply when using the JSONP interface.  Under JSONP, every API call results in a 200 OK regardless of its actual error state (this is because the <script> tag injection won't work with any other status code).  When they occur, errors will be reported as part of the result object using the following special fields:

JSONP Response Field Purpose Equivalent using normal JSON
data.ok Indicates success (true) or failure (false) none
data.status Indicates the response status code HTTP response status
data.error Indicates the error message, if any HTTP response body, or X-Error-Detail HTTP header

Starting with version 1.2, the jQuery JavaScript framework includes native support for JSONP.  Here's a very simple application, written using jQuery:

<html>
<head>
<title>Etsy jQuery Demo</title>
<script type="application/javascript" src="jquery-1.3.2.min.js"></script>
<script type="application/javascript">
$.getJSON("http://beta-api.etsy.com/v1/listings/featured/front.js?limit=12&callback=?&api_key=<your_api_key>", function(data) {
      if (data.ok) {
            $.each(data.results, function(i,item) {
                  $("<img/>").attr("src", item.image_url_75x75).appendTo("#images").wrap("<a href='" + item.url + "'></a>");
            });
        } else {
            alert(data.error);
      }
});

</script>
</head>
<body>
<div id="images"></div>
</body>
</html>

If you save this code and view it in your browser, you should see the current front-page featured listings on Etsy.com (don't forget to download jQuery and place it in the same directory!)

Notice that using jQuery, it's not necessary to pick your own value for callback.  Simply pass a question mark, and jQuery will generate a callback function and substitute its name in the URL.  jQuery will also clean up the callback function after the call is finished.

↑ Back to top.

Resource Types

Each command in the Etsy API will return objects of one of the following types:

  • Users - represent a single user of the site, who may or may not be a seller.
  • Shops - extend user records to include information about the seller's shop.
  • Shop Sections - organize a shop's listing into categories.
  • Listings - represent an item for sale on Etsy.
  • Gift Guides - represents a collection of listings that have been selected by the Etsy staff around different themes.
  • Tags - represent seller-supplied tags on Etsy listings.
  • Categories - represent listing categories on the Etsy website.
  • Feedback - comments left by buyers or sellers about a specific transaction.
  • Methods - represents a single command of the Etsy API.

A command always returns objects of only one type, and the same command will always return the same type, no matter its input. (Exception: Shop Section is a subtype, nested inside Shop objects.)

Users

User records represent a single user of the site, who may or may not be a seller.

Field Min. Detail Level Type Description
user_name low string The user's login name.
user_id low int The user's numeric ID.  This is also valid as the user's shop ID.
url low string The full URL to the user's shop, if s/he is a seller, or to the user's public profile.
image_url_25x25 low string The full URL to the user's 25x25 avatar thumbnail.
image_url_30x30 low string The full URL to the user's 30x30 avatar thumbnail.
image_url_50x50 low string The full URL to the user's 50x50 avatar thumbnail.
image_url_75x75 low string The full URL to the user's 75x75 avatar (full resolution).
join_epoch low float The date and time the user joined the site, in epoch seconds.
city low string The user's city and state (freeform entry; may be blank).
gender medium string The user's gender (female, male, or private).
lat medium float The user's latitude (may be blank).
lon medium float The user's longitude (may be blank).
transaction_buy_count medium int The number of items the user has purchased.
transaction_sold_count medium int The number of items the user has sold.
is_seller medium boolean true if user is a seller.
was_featured_seller medium boolean true if user was previously featured.
materials medium string The user's favorite materials.
last_login_epoch medium float The date and time of the user's last login, in epoch seconds.
user_image_id high int The numeric ID of the user's avatar image.
referred_user_count high int The number of members the user has referred to the site.
birth_day high int The day portion of the user's birthday (may be blank).
birth_month high int The month portion of the user's birthday (may be blank).
bio high string The user's biography (may be blank).
feedback_count high int The total count of feedback by and about this user.
feedback_percent_positive high int The percentage of feedback by or about this user that is positive.
favorite_creation_epoch favorites float The date and time that the user was favorited (only available in the commands getFavorersOfShop, getFavorersOfListing and getFavoriteShopsOfUser.)
status favorites enum(public, private) If private, user is a Secret Admirer, and no information about the user can be shown.

Shops

Shop records extend user records to include information about the seller's shop. In addition to all the user fields listed above; shops have these additional fields:

Field Min. Detail Level Type Description
banner_image_url low string The full URL to the shops's banner image.
last_updated_epoch low string The date and time the shop was last updated, in epoch seconds.
creation_epoch low string The date and time the shop was created, in epoch seconds.
listing_count low int The number of active listings in the shop.
shop_name medium string The shop's name.
title medium string A brief heading for the shop's main page.
sale_message medium string A message that is sent to users who buy from this shop.
announcement high string An announcement to buyers that displays on the shop's homepage.
is_vacation high int If the seller is not currently accepting purchases, 1, blank otherwise.
vacation_message high string If is_vacation=1, a message to buyers.
currency_code high string The ISO code (alphabetic) for the seller's native currency.
policy_welcome high string The introductory text from the top of the seller's policies page (may be blank).
policy_payment high string The seller's policy on payment (may be blank).
policy_shipping high string The seller's policy on shippinh (may be blank).
policy_refunds high string The seller's policy on refunds (may be blank).
policy_additional high string Any additional policy information the seller provides (may be blank).
sections high array(shop-section) An array of shop-section objects (see below).

Shop Sections

Some sellers may choose to organize their listings into sections.  Each section is specific to a shop and has a numeric ID and a title.

Field Type Description
section_id int The numeric ID of the shop section.
title string The title of the section.
listing_count int The number of active listings currently in the section.

Listings

Listing records represent an item for sale on Etsy.

Field Min. Detail Level Type Description
listing_id low int The numeric ID for this listing.
state low string One of active, removed, soldout, expired, or alchemy.
title low string The listing's title.
url low string The full URL to the listing's page.
image_url_25x25 low string The full URL to a 25x25 thumbnail of the listing's image.
image_url_50x50 low string The full URL to a 50x50 thumbnail of the listing's image.
image_url_75x75 low string The full URL to a 75x75 thumbnail of the listing's image.
image_url_155x125 low string The full URL to a 155x125 thumbnail of the listing's image.
image_url_200x200 low string The full URL to a 200x200 thumbnail of the listing's image.
image_url_430xN low string The full URL to the listing's image, always 430 pixels wide.
creation_epoch low float The date and time the listing was posted, in epoch seconds.
views medium int How many times the item has been viewed.
tags medium array(string) A list of tags for the item.
materials medium array(string) A list of materials used in the item.
price medium float The item's price.
currency_code medium string The ISO (alphabetic) code for the item's currency.
ending_epoch medium float The listing's expiration date and time, in epoch seconds.
user_id medium int The numeric ID of the user who posted the item. (User IDs are also shop IDs).
user_name medium string The login name of the user who posted the item.
quantity medium int The quantity of this item available for sale.
hsv_color medium array(int) The average color of the listing's primary image, in HSV format.
rgb_color medium string The average color of the listing's primary image, in RGB hexadecimal ("web") format.
description high string A description of the item.
lat high float The latitude of the user selling the item (may be blank).
lon high float The longitude of the user selling the item (may be blank).
city high string The user's city and state (user-supplied; may be blank).
section_id high int If the shop uses sections, the numeric ID of the section to which this listing belongs.
section_title high string The title of the section to which this listing belongs.
all_images high array(image) An array of image objects (see below.)
favorite_creation_epoch favorites float The date and time that the user was favorited (only available in the command getFavoriteListingsOfUser.)
score low float Search relevancy score (only when sorting a search on "score".)

Images

Images are a subtype of Listings and will appear when detail_level is high.

Field Type Description
image_url_25x25 string The full URL to a 25x25 thumbnail of the listing's image.
image_url_50x50 string The full URL to a 50x50 thumbnail of the listing's image.
image_url_75x75 string The full URL to a 75x75 thumbnail of the listing's image.
image_url_155x125 string The full URL to a 155x25 thumbnail of the listing's image.
image_url_200x200 string The full URL to a 200x200 thumbnail of the listing's image.
image_url_430xN string The full URL to the listing's image, always 430 pixels wide.
hsv_color array(int) The average color of the image, in HSV format.
rgb_color string The average color of the image, in RGB hexadecimal ("web") format.

Gift Guides

Gift guides display summary information about each gift guide on the Etsy website.  Gift Guides don't support the detail_level parameter; all fields are available at all times.

Field Type Description
guide_id int The numeric ID of this guide.
creation_tsz_epoch float The date and time the gift guide was created, in epoch seconds.
description string A short description of the guide
title string The guide's main title.
display_order int A field on which the guides can be sorted.
guide_section_id int The numeric ID of the guide's parent section.
guide_section_title string The title of the guide's parent section.

Tags

Tags are represented by arrays of string values; they don't have fields.

When a seller lists an item on Etsy, she or he tags the listings with various keywords.  These tags are free-form and form the basis for Etsy's categories hierarchy, described below.  Listings can be searched by tag name.

Categories

Categories are represented by string values; they don't have fields. Categories on Etsy are built up from the most popular tags.  Each category name is a chain of one to three tags, separated by colons (":").  Navigating through these categories using the getChildCategories command will produce the same results as clicking through the category links on the Etsy website.  The getListingsByCategory command will return the same listings as found on the corresponding Etsy page. You may notice that the getTopCategories command returns exactly the same data as getTopTags.  Because categories are built up from tags, at the top level they are in fact the same.  The two different commands are included for clarity's sake.

Feedback

Feedback records represent a comment left by either the buyer or seller in a transaction.  Every sale on Etsy creates two opportunities for a user to leave feedback: one, by the buyer commenting on the seller, and the second by the seller commenting on the buyer.

Field Type Description
feedback_id int The numeric ID of the feedback record.
listing_id int The numeric ID of the sold item.
title string The sold item's title.
url string The fully-qualified URL to the sold item's listing page.
creation_epoch float The date and time the feedback was posted, in epoch seconds.
author_user_id int The user ID of the person user leaving the feedback.
subject_user_id int The user ID of the person receiving feedback.
seller_user_id int The user ID of the user acting as seller in this transaction.
buyer_user_id int The user ID of the user acting as buyer in this transaction.
message string A short message, left by the author.
disposition enum(positive, neutral, negative) One of positive, neutral or negative.
value int The numeric value of the feedback disposition (-1..1).
image_url_25x25 string The full URL to a thumbnail of an image posted by the feedback author (may be blank).
image_url_fullxfull string The full URL to an image posted by the feedback author (may be blank).

Methods

Method records are returned by the getMethodTable command, which lists all the functionality available in the Etsy API. Method records don't support the detail_level parameter; all fields are available at all times.

Field Type Description
name string A descriptive name for the command.
description string Brief text explaining the method.
uri string The method's relative URI pattern with embedded parameters in curly braces ("{" and "}").
params hash A hash of param names as keys, and types as values. Valid types are string, int, enum (with values in parentheses) and user_id_or_name.
type string The return type of this method. Valid return types are user, shop, listing, tag, gift-guide and method.
http_method string The HTTP method used in this call.  Currently all methods accept only GET. Future version of the Etsy API will accept POST, PUT and DELETE.

↑ Back to top.

Commands

User Commands

getUserDetails

Method Name getUserDetails
Synopsis Get the details of a user.
HTTP Method GET
URI /users/{user_id}
Parameters
Name Required Default Type
user_id Y   user_id_or_name
detail_level N low enum(low, medium, high)
Return Type user
  • Specify the user's numeric ID or login name with user_id. (Shops and users share the same IDs.)
  • Control how much information to return with detail_level. (See Resource Types for details.)

getUsersByName

Method Name getUsersByName
Synopsis Search active users alphabetically by user_name.
HTTP Method GET
URI /users/keywords/{search_name}
Parameters
Name Required Default Type
search_name Y   string
offset N 0 int
limit N 10 int
detail_level N low enum(low, medium, high)
Return Type user
  • Set search name to part or all of a user's login name.
  • To page through large result sets, set offset to a multiple of limit.
  • Specify the number of results to return with limit.
  • Control how much information to return with detail_level. (See Resource Types for details.)

See Also

↑ Back to top.

Shop Commands

getShopDetails

Method Name getShopDetails
Synopsis Get the details of a seller's shop.
HTTP Method GET
URI /shops/{user_id}
Parameters
Name Required Default Type
user_id Y   user_id_or_name
detail_level N low enum(low, medium, high)
Return Type shop
  • Specify the user's numeric ID or login name with user_id. (Shops and users share the same IDs.)
  • Control how much information to return with detail_level. (See Resource Types for details.)

getShopListings

Method Name getShopListings
Synopsis Get all the listings in a shop.
HTTP Method GET
URI /shops/{user_id}/listings
Parameters
Name Required Default Type
user_id Y   user_id_or_name
sort_on N created enum(created, price)
sort_order N down enum(up, down)
section_id N NULL int
offset N 0 int
limit N 10 int
detail_level N low enum(low, medium, high)
Return Type listing
  • Specify the user's numeric ID or login name with user_id. (Shops and users share the same IDs.)
  • Specify the field to sort on with sort_on.
  • Specify the direction to sort on with sort_order.
  • Specify the numeric ID of a shop section with section_id (optional).
  • To page through large result sets, set offset to a multiple of limit.
  • Specify the number of results to return with limit.
  • Control how much information to return with detail_level. (See Resource Types for details.)

getFeaturedDetails

Method Name getFeaturedDetails
Synopsis Get the expanded details on featured listings of a shop, ordered by highest ranked featured item.
HTTP Method GET
URI /shops/{user_id}/listings/featured
Parameters
Name Required Default Type
user_id Y   user_id_or_name
detail_level N low enum(low, medium, high)
Return Type listing
  • Specify the user's numeric ID or login name with user_id. (Shops and users share the same IDs.)
  • Control how much information to return with detail_level. (See Resource Types for details.)

getFeaturedSellers

Method Name getFeaturedSellers
Synopsis Get a list of all the featured sellers.
HTTP Method GET
URI /shops/featured
Parameters
Name Required Default Type
offset N 0 int
limit N 10 int
detail_level N low enum(low, medium, high)
Return Type shop
  • To page through large result sets, set offset to a multiple of limit.
  • Specify the number of results to return with limit.
  • Control how much information to return with detail_level. (See Resource Types for details.)

getShopsByName

Method Name getShopsByName
Synopsis Search all active shops sorted alphabetically by user_name.
HTTP Method GET
URI /shops/keywords/{search_name}
Parameters
Name Required Default Type
search_name Y   string
sort_order N down enum(up, down)
offset N 0 int
limit N 10 int
detail_level N low enum(low, medium, high)
Return Type shop
  • Set search name to part or all of a user's login name.
  • Specify the direction to sort on with sort_order.
  • To page through large result sets, set offset to a multiple of limit.
  • Specify the number of results to return with limit.
  • Control how much information to return with detail_level. (See Resource Types for details.)

See Also

↑ Back to top.

Listing Commands

getListingDetails

Method Name getListingDetails
Synopsis Get the details of a listing.
HTTP Method GET
URI /listings/{listing_id}
Parameters
Name Required Default Type
listing_id Y   int
detail_level N low enum(low, medium, high)
Return Type listing
  • Specify the listing's numeric ID with listing_id.
  • Control how much information to return with detail_level. (See Resource Types for details.)

getAllListings

Method Name getAllListings
Synopsis Get all active listings on Etsy.
HTTP Method GET
URI /listings/all
Parameters
Name Required Default Type
sort_on N created enum(created, ending)
sort_order N down enum(up, down)
offset N 0 int
limit N 10 int
detail_level N low enum(low, medium, high)
Return Type listing
  • Specify the field to sort on with sort_on.
  • Specify the direction to sort on with sort_order.
  • To page through large result sets, set offset to a multiple of limit.
  • Specify the number of results to return with limit.
  • Control how much information to return with detail_level. (See Resource Types for details.)

getListingsByCategory

Method Name getListingsByCategory
Synopsis Search for listings by category.
HTTP Method GET
URI /listings/category/{category}
Parameters
Name Required Default Type
category Y   string
sort_on N created enum(created, price)
sort_order N down enum(up, down)
offset N 0 int
limit N 10 int
detail_level N low enum(low, medium, high)
Return Type listing
  • Specify the field to sort on with sort_on.
  • Specify the direction to sort on with sort_order.
  • To page through large result sets, set offset to a multiple of limit.
  • Specify the number of results to return with limit.
  • Control how much information to return with detail_level. (See Resource Types for details.)

getListingsByColor

Method Name getListingsByColor
Synopsis Search for listings by average color of primary image.
HTTP Method GET
URI /listings/color/{color}
Parameters
Name Required Default Type
color Y   color_triplet
wiggle N 5 int
offset N 0 int
limit N 10 int
detail_level N low enum(low, medium, high)
Return Type listing
  • Specify an HSV color as an array (0;0;0 through 360;100;100) or an RGB color in web notation (#000000 through #FFFFFF.) NOTE: The Etsy API uses HSV colors internally, and the conversion from RGB to HSV is not 100% accurate.
  • Specify the degree of tolerance for color matching with wiggle; where 0 is the most accurate, and 15 is the least.
  • To page through large result sets, set offset to a multiple of limit.
  • Specify the number of results to return with limit.
  • Control how much information to return with detail_level. (See Resource Types for details.)

getListingsByColorAndKeywords

Method Name getListingsByColorAndKeywords
Synopsis Search for listings by keywords and average color of primary image.
HTTP Method GET
URI /listings/color/{color}/keywords/{search_terms}
Parameters
Name Required Default Type
search_terms Y   array(string)
color Y   color_triplet
wiggle N 5 int
offset N 0 int
limit N 10 int
detail_level N low enum(low, medium, high)
Return Type listing
  • Specify keywords to search on with search_terms, separated by spaces or semicolons. You can also use the operators AND and NOT to control keyword matching.
  • Specify an HSV color as an array (0;0;0 through 360;100;100) or an RGB color in web notation (#000000 through #FFFFFF.) NOTE: The Etsy API uses HSV colors internally, and the conversion from RGB to HSV is not 100% accurate.
  • Specify the degree of tolerance for color matching with wiggle; where 0 is the most accurate, and 15 is the least.
  • To page through large result sets, set offset to a multiple of limit.
  • Specify the number of results to return with limit.
  • Control how much information to return with detail_level. (See Resource Types for details.)

getFrontFeaturedListings

Method Name getFrontFeaturedListings
Synopsis Get the featured listings on the front page for the current day.
HTTP Method GET
URI /listings/featured/front
Parameters
Name Required Default Type
offset N 0 int
limit N 10 int
detail_level N low enum(low, medium, high)
Return Type listing
  • To page through large result sets, set offset to a multiple of limit.
  • Specify the number of results to return with limit.
  • Control how much information to return with detail_level. (See Resource Types for details.)

getListingsByKeyword

Method Name getListingsByKeyword
Synopsis Search for listings by keyword.
HTTP Method GET
URI /listings/keywords/{search_terms}
Parameters
Name Required Default Type
search_terms Y   array(string)
sort_on N created enum(created, price, score)
sort_order N down enum(up, down)
min_price N NULL float
max_price N NULL float
search_description N false enum(true, false)
limit N 10 int
offset N 0 int
detail_level N low enum(low, medium, high)
Return Type listing
  • Specify keywords to search on with search_terms, separated by spaces or semicolons. You can also use the operators AND and NOT to control keyword matching.
  • Specify the field to sort on with sort_on.
  • Specify the direction to sort on with sort_order.
  • Restrict price ranges with min_price and max_price. Values are in US dollars and may include cents.
  • If search_description is true, listing descriptions will count towards search matches. (This may produce less relevant results.)
  • Specify the number of results to return with limit.
  • To page through large result sets, set offset to a multiple of limit.
  • Control how much information to return with detail_level. (See Resource Types for details.)

getListingsByMaterials

Method Name getListingsByMaterials
Synopsis Search for listings by materials used.
HTTP Method GET
URI /listings/materials/{materials}
Parameters
Name Required Default Type
materials Y   array(string)
sort_on N created enum(created, price, score)
sort_order N down enum(up, down)
offset N 0 int
limit N 10 int
detail_level N low enum(low, medium, high)
Return Type listing
  • Specify one or more materials with materials, separated by spaces or semicolons.
  • Specify the field to sort on with sort_on.
  • Specify the direction to sort on with sort_order.
  • To page through large result sets, set offset to a multiple of limit.
  • Specify the number of results to return with limit.
  • Control how much information to return with detail_level. (See Resource Types for details.)

getListingsByTags

Method Name getListingsByTags
Synopsis Search for listings by tags.
HTTP Method GET
URI /listings/tags/{tags}
Parameters
Name Required Default Type
tags Y   array(string)
sort_on N created enum(created, price, score)
sort_order N down enum(up, down)
offset N 0 int
limit N 10 int
detail_level N low enum(low, medium, high)
Return Type listing
  • Specify one or more tags with tags, separated by spaces or semicolons.
  • Specify the field to sort on with sort_on.
  • Specify the direction to sort on with sort_order.
  • To page through large result sets, set offset to a multiple of limit.
  • Specify the number of results to return with limit.
  • Control how much information to return with detail_level. (See Resource Types for details.)

See Also

↑ Back to top.

Feedback Commands

getFeedback

Method Name getFeedback
Synopsis Get a feedback record.
HTTP Method GET
URI /feedback/{feedback_id}
Parameters
Name Required Default Type
feedback_id Y   int
Return Type feedback

getFeedbackForUser

Method Name getFeedbackForUser
Synopsis Get a list of all feedback for a particular user.
HTTP Method GET
URI /users/{user_id}/feedback
Parameters
Name Required Default Type
user_id Y   user_id_or_name
limit N 10 int
offset N 0 int
Return Type feedback
  • Specify the user's numeric ID or login name with user_id. (Shops and users share the same IDs.)
  • Specify the number of results to return with limit.
  • To page through large result sets, set offset to a multiple of limit.

getFeedbackAsBuyer

Method Name getFeedbackAsBuyer
Synopsis Get a list of all feedback where the user was a buyer in the transaction.
HTTP Method GET
URI /users/{user_id}/feedback/buyer
Parameters
Name Required Default Type
user_id Y   user_id_or_name
limit N 10 int
offset N 0 int
Return Type feedback
  • Specify the user's numeric ID or login name with user_id. (Shops and users share the same IDs.)
  • Specify the number of results to return with limit.
  • To page through large result sets, set offset to a multiple of limit.

getFeedbackForOthers

Method Name getFeedbackForOthers
Synopsis Get a list of all feedback that the user left feedback for someone else.
HTTP Method GET
URI /users/{user_id}/feedback/others
Parameters
Name Required Default Type
user_id Y   user_id_or_name
limit N 10 int
offset N 0 int
Return Type feedback
  • Specify the user's numeric ID or login name with user_id. (Shops and users share the same IDs.)
  • Specify the number of results to return with limit.
  • To page through large result sets, set offset to a multiple of limit.

getFeedbackAsSeller

Method Name getFeedbackAsSeller
Synopsis Get a list of all feedback where the user was a seller in the transaction.
HTTP Method GET
URI /users/{user_id}/feedback/seller
Parameters
Name Required Default Type
user_id Y   user_id_or_name
limit N 10 int
offset N 0 int
Return Type feedback
  • Specify the user's numeric ID or login name with user_id. (Shops and users share the same IDs.)
  • Specify the number of results to return with limit.
  • To page through large result sets, set offset to a multiple of limit.

↑ Back to top.

Tag and Category Commands

getTopCategories

Method Name getTopCategories
Synopsis Get the list of current top level categories.
HTTP Method GET
URI /categories
Parameters none
Return Type category

getChildCategories

Method Name getChildCategories
Synopsis Get the child categories of a category.
HTTP Method GET
URI /categories/{category}/children
Parameters
Name Required Default Type
category Y   string
Return Type category

getTopTags

Method Name getTopTags
Synopsis Get the list of current top level tags.
HTTP Method GET
URI /tags
Parameters none
Return Type tag

getChildTags

Method Name getChildTags
Synopsis Get the child tags of a tag.
HTTP Method GET
URI /tags/{tag}/children
Parameters
Name Required Default Type
tag Y   string
Return Type tag
  • Specify a single tag name with tag.

See Also

↑ Back to top.

Favorites Commands

getFavorersOfListing

Method Name getFavorersOfListing
Synopsis Get all the users who call this listing a favorite.
HTTP Method GET
URI /listings/{listing_id}/favorers
Parameters
Name Required Default Type
listing_id Y   int
offset N 0 int
limit N 10 int
detail_level N low enum(low, medium, high)
Return Type user
  • Specify the listing's numeric ID with listing_id.
  • To page through large result sets, set offset to a multiple of limit.
  • Specify the number of results to return with limit.
  • Control how much information to return with detail_level. (See Resource Types for details.)

getFavorersOfShop

Method Name getFavorersOfShop
Synopsis Get all the users who call this shop a favorite.
HTTP Method GET
URI /shops/{user_id}/favorers
Parameters
Name Required Default Type
user_id Y   user_id_or_name
offset N 0 int
limit N 10 int
detail_level N low enum(low, medium, high)
Return Type user
  • Specify the user's numeric ID or login name with user_id. (Shops and users share the same IDs.)
  • To page through large result sets, set offset to a multiple of limit.
  • Specify the number of results to return with limit.
  • Control how much information to return with detail_level. (See Resource Types for details.)

getFavoriteListingsOfUser

Method Name getFavoriteListingsOfUser
Synopsis Get the favorite listings of a user.
HTTP Method GET
URI /users/{user_id}/favorites/listings
Parameters
Name Required Default Type
user_id Y   user_id_or_name
offset N 0 int
limit N 10 int
detail_level N low enum(low, medium, high)
Return Type listing
  • Specify the user's numeric ID or login name with user_id. (Shops and users share the same IDs.)
  • To page through large result sets, set offset to a multiple of limit.
  • Specify the number of results to return with limit.
  • Control how much information to return with detail_level. (See Resource Types for details.)

getFavoriteShopsOfUser

Method Name getFavoriteShopsOfUser
Synopsis Get the favorite shops of a user.
HTTP Method GET
URI /users/{user_id}/favorites/shops
Parameters
Name Required Default Type
user_id Y   user_id_or_name
offset N 0 int
limit N 10 int
detail_level N low enum(low, medium, high)
Return Type shop
  • Specify the user's numeric ID or login name with user_id. (Shops and users share the same IDs.)
  • To page through large result sets, set offset to a multiple of limit.
  • Specify the number of results to return with limit.
  • Control how much information to return with detail_level. (See Resource Types for details.)

↑ Back to top.

Gift Guide Commands

getGiftGuides

Method Name getGiftGuides
Synopsis Get a list of gift guides.
HTTP Method GET
URI /gift-guides
Parameters none
Return Type gift-guide

getGiftGuideListings

Method Name getGiftGuideListings
Synopsis Get the listings in a gift guide.
HTTP Method GET
URI /gift-guides/{guide_id}/listings
Parameters
Name Required Default Type
guide_id Y   int
offset N 0 int
limit N 10 int
detail_level N low enum(low, medium, high)
Return Type listing
  • Specify the numeric ID of a Gift Guide with guide_id.
  • To page through large result sets, set offset to a multiple of limit.
  • Specify the number of results to return with limit.
  • Control how much information to return with detail_level. (See Resource Types for details.)

↑ Back to top.

Server Commands

getMethodTable

Method Name getMethodTable
Synopsis Get a list of all methods available.
HTTP Method GET
URI /
Parameters none
Return Type method

getServerEpoch

Method Name getServerEpoch
Synopsis Get server time, in epoch seconds notation.
HTTP Method GET
URI /server/epoch
Parameters none
Return Type int

ping

Method Name ping
Synopsis Check that the server is alive.
HTTP Method GET
URI /server/ping
Parameters none
Return Type string

↑ Back to top.

version 47 as of 3 weeks ago by Rachel

Comments

New comments are not being accepted at this time.

Docs Navigation