Navigating the Etsy API
I recently finished a project that required the use of the Etsy API and was so excited to find such a well-documented and useful API. Hopefully there will be more projects to come using the wide spectrum of data available from this single source.
First, let’s cover the basic of using an API in python. To import data from an API, we’ll use a GET request along with the API URL. I like to keep the arguments for my GET requests as independent variables.
We’ll then check the response status code to make sure the request was… well, properly requested. Anything other than a 200 status code calls for some investigation. A complete list of status codes can be found here.
url = 'https://openapi.etsy.com/v2/listings/active?'
params = {'api_key': 'YOUR API KEY'}response = requests.get(url = url, params = params)response.status_code
Etsy’s response is in a JSON format, so to view the data we’ll want to use the .json() method.
etsy_data = response.json()Great! Those are your basics we need to cover before talking more specifically about Etsy’s API — so let’s get started!
Before jumping straight into an API, be sure to read the documentation first. Etsy’s is very thorough and helpful. Basic documentation is linked here. This includes data type, parameter options, instructions on getting an API key, and much more. At the top of this page, all of the API’s references are linked. These references allow the user to pull certain information.
Let’s say we wanted to look at current product listings for coasters, we’d use the “Listing” reference with a parameter to narrow our search for coasters. Included in the documentation for each reference are the fields available, we’ll use the tags field as a parameter to look for coasters and limit our returned listings to 5.
params = {'api_key': 'YOUR API KEY', 'tags': ['coaster'], 'limit': 5}response = requests.get(url = url, params = params)
etsy_listings = reponse.json()
etsy_listings.keys()dict_keys(['count', 'results', 'params', 'type', 'pagination'])
We see that we have a dictionary with keys for count, results, params, type, and pagination. Note that calling ‘results’ will leave us with a list. Indexing through the list will get us a dictionary for each listing. Let’s take a look.
results = etsy_listings['results']
first_listing = results[0]
first_listing.keys()dict_keys(['listing_id', 'state', 'user_id', 'category_id', 'title', 'description', 'creation_tsz', 'ending_tsz', 'original_creation_tsz', 'last_modified_tsz', 'price', 'currency_code', 'quantity', 'sku', 'tags', 'materials', 'shop_section_id', 'featured_rank', 'state_tsz', 'url', 'views', 'num_favorers', 'shipping_template_id', 'processing_min', 'processing_max', 'who_made', 'is_supply', 'when_made', 'item_weight', 'item_weight_unit', 'item_length', 'item_width', 'item_height', 'item_dimensions_unit', 'is_private', 'recipient', 'occasion', 'style', 'non_taxable', 'is_customizable', 'is_digital', 'file_data', 'should_auto_renew', 'language', 'has_variations', 'taxonomy_id', 'taxonomy_path', 'used_manufacturer', 'is_vintage'])
We can see our results include a ton of information from a product’s price to whether or not it’s vintage. From here, the world is your oyster! I like to choose the keys I want to work with and put them into a DataFrame for easy cleaning and visualization — but the options are endless.
This short blog only covers one of Etsy’s many references, don’t forget to visit their API documentation and take a look at the others. They span from images, user profiles and addresses to payments and shipping information.
Thanks for reading! Hopefully this gave you a good idea of how to easily maneuver through an API.
