Skip to main content
Help us improve PyPI by participating in user testing. All experience levels needed!

Python wrapper for the Etsy api

Project description


To make it easier to interact with the Etsy API in Python.


sudp pip install python-etsy



>>> from etsy import Etsy
>>> e = Etsy(consumer_key, consumer_secret) # gotten from signing up at

Get info for user

>>> e.get_user_info('priestc')
{u'count': 1,
 u'pagination': {},
 u'params': {u'user_id': u'priestc'},
 u'results': [{u'creation_tsz': 1338405910,
   u'feedback_info': {u'count': 0, u'score': None},
   u'login_name': u'priestc',
   u'referred_by_user_id': None,
   u'user_id': 22138099}],
 u'type': u'User'}

Searching for users

>>> e.find_user('william')
{u'count': 27956,
 u'pagination': {u'effective_limit': 25,
  u'effective_offset': 0,
  u'effective_page': 1,
  u'next_offset': 25,
  u'next_page': 2},
 u'params': {u'keywords': u'william',
  u'limit': 25,
  u'offset': 0,
  u'page': None},
 u'results': [{u'creation_tsz': 1320715538,
   u'feedback_info': {u'count': 0, u'score': None},
   u'login_name': u'almostbohemian',
   u'referred_by_user_id': None,
   u'user_id': 17479899},
  {u'creation_tsz': 1335125907,
   u'feedback_info': {u'count': 0, u'score': None},
   u'login_name': u'Blawesomes',
   u'referred_by_user_id': None,
   u'user_id': 21276820},
  {u'creation_tsz': 1339310987,
   u'feedback_info': {u'count': 0, u'score': None},
   u'login_name': u'cityfleet',
   u'referred_by_user_id': None,
   u'user_id': 22385428},
  {u'creation_tsz': 1321655636,
   u'feedback_info': {u'count': 2, u'score': 100},
   u'login_name': u'way2easy4ron',
   u'referred_by_user_id': None,

Showing listings

Listings are items that are for sale on the site.

>>> e.show_listings(color='#FF00FF')
{u'count': 15,
 u'pagination': {u'effective_limit': 25,
  u'effective_offset': 0,
  u'effective_page': 1,
  u'next_offset': None,
  u'next_page': None},
 u'params': {u'category': None,
  u'color': u'#FF0000',
  u'color_accuracy': u'5',
  u'geo_level': u'city',
  u'keywords': None,
  u'lat': None,
  u'limit': 25,
  u'location': None,
  u'lon': None,
  u'materials': None,
  u'max_price': None,
  u'min_price': None,
  u'offset': 0,
  u'page': None,
  u'sort_on': u'created',
  u'sort_order': u'down',
  u'tags': None},
 u'results': [{u'brightness': 99,
   u'category_id': 69152465,
   u'category_path': [u'Patterns', u'Handmade'],
   u'creation_tsz': 1343606971,
   u'currency_code': u'USD',
   u'description': u'This listing is for...',
   u'ending_tsz': 1354165200,
   u'featured_rank': 0,
   u'hue': 0,
   u'is_black_and_white': False,
   u'is_supply': None,
   u'last_modified_tsz': 1343606971,
   u'listing_id': 55489116,
   u'materials': [u'pdf email pattern', u'beads', u'needles and thread'],
   u'num_favorers': 4,
   u'occasion': None,
   u'original_creation_tsz': 1283592254,
   u'price': u'35.00',
   u'quantity': 1,
   u'recipient': None,
   u'saturation': 100,
   u'shop_section_id': 6766997,
   u'state': u'active',
   u'state_tsz': 1323227794,
   u'style': None,
   u'tags': [u'beading',
    u'snow leopard',
    u'dust team',
    u'ebw team'],

Authenticating with OAuth

>>> e.get_auth_url(permissions=['email_r', 'listings_r'])
 'oauth_token_secret': u'XXXXXXXXXX',
 'url': u''}

The user then is redirected to the URL (you must save the oauth_token and oauth_token_secret for later in step two).

The list of all permissions can be found [here.](

Once the user click the link and authenticates your app, the user then copy/pastes the verification code back to your app

>>> e.get_auth_token(verification_code, oauth_token, oauth_token_secret)
 'oauth_token_secret': u'XXXXXXXXXXXX'}

The new oauth_token and oauth_token_secret are permanent and should be stored in a database for use in all subsequent api requests that require authentication.

Making authenticated requests

When instantiating the Etsy object, include the oauth_token and oauth_token_secret along with the consumer_key and consumer_secret:

>>> from etsy import Etsy
>>> e = Etsy(consumer_key, consumer_secret, oauth_token, oauth_token_secret)

Now you have access to all authentication only methods, as well as the magic __SELF__ identifier:

>>> e.get_user_info('__SELF__')
{u'count': 1,
 u'pagination': {},
 u'params': {u'user_id': u'__SELF__'},
 u'results': [{u'creation_tsz': 1344140248,
   u'feedback_info': {u'count': 0, u'score': None},
   u'login_name': u'priestc',
   u'primary_email': u'',
   u'referred_by_user_id': None,
   u'user_id': 14888663}],
 u'type': u'User'}

Notice the addition of the primary_email field, this is because this user authenticated with the app using the ‘email_r’ permission.

Project details

Release history Release notifications

This version
History Node


History Node


History Node


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Filename, size & hash SHA256 hash help File type Python version Upload date
python-etsy-0.1.2.macosx-10.7-intel.exe (71.4 kB) Copy SHA256 hash SHA256 Windows Installer any Aug 6, 2012
python-etsy-0.1.2.tar.gz (5.0 kB) Copy SHA256 hash SHA256 Source None Aug 6, 2012

Supported by

Elastic Elastic Search Pingdom Pingdom Monitoring Google Google BigQuery Sentry Sentry Error logging CloudAMQP CloudAMQP RabbitMQ AWS AWS Cloud computing Fastly Fastly CDN DigiCert DigiCert EV certificate StatusPage StatusPage Status page