Etsy APIetsy.com ↗
Access Etsy product listings, shop profiles, reviews, and category browsing via 7 structured endpoints. Filter by price, category, or keyword.
What is the Etsy API?
The Etsy API exposes 7 endpoints covering product search, category browsing, listing details, shop profiles, shop listings, shop search, and reviews. The get_listing_details endpoint returns up to 12 fields per listing — including tags, badges like 'Bestseller', view counts, favorites, and multi-image arrays — while search_listings supports keyword queries with price range, vintage, and handmade filters.
curl -X GET 'https://api.parse.bot/scraper/f1489504-16f1-487c-930b-1347ea210416/search_listings?page=1&query=ceramic+mug' \ -H 'X-API-Key: $PARSE_API_KEY'
Typed, relational, agent-ready
A generated client with real types, enums, and the links between objects — the structure a flat JSON response can't carry. Autocompletes in your editor and reads cleanly to coding agents.
- Fully typed · autocompletes
- Objects link to objects
- Typed errors & pagination
Typed Python client. Set up the SDK in your uv project, then pull this API’s typed client:
uv add parse-sdk uv run parse init uv run parse add --marketplace etsy-com-api
uv run parse add --marketplace pulls a pinned snapshot of this canonical API — it won’t change underneath you. To customize it, subscribe and swap to your own copy.
"""Walkthrough: Etsy SDK — browse categories, search listings, get details and reviews, search shops."""
from parse_apis.etsy_scraper_api import Etsy, ListingNotFound
client = Etsy()
# Browse rings in the jewelry category — limit caps total items fetched.
for item in client.category("jewelry/rings").browse(limit=3):
print(item.name, item.price)
# Search for listings by keyword.
result = client.listingsummaries.search(query="handmade candle", limit=1).first()
if result:
print(result.name, result.price, result.listing_id)
# Drill into a listing for full details.
listing = client.category("jewelry/necklaces").browse(limit=1).first()
if listing:
detail = listing.details()
print(detail.name, detail.price, detail.currency, detail.shop_name)
print("Tags:", detail.tags[:3])
# Fetch reviews for this listing.
review_result = detail.reviews()
for rev in review_result.all_shop_reviews_sample[:2]:
print(rev.rating, rev.buyer_display_name, rev.review[:60] if rev.review else "")
# Get a shop's profile and browse its listings.
shop = client.shops.get(shop_name="TheBeadChest")
print(shop.name, shop.rating, shop.review_count)
for item in shop.listings(limit=3):
print(item.name, item.price)
# Typed error handling: catch a missing listing gracefully.
try:
client.listings.get(listing_id="9999999999999")
except ListingNotFound as exc:
print(f"Listing not found: {exc.listing_id}")
print("exercised: category.browse / listingsummaries.search / listing.details / listing.reviews / shops.get / shop.listings / listings.get")
Search for product listings on Etsy by keyword. Returns paginated results with basic product information extracted from structured data. Supports optional price range and attribute filters.
| Param | Type | Description |
|---|---|---|
| page | integer | Page number for pagination. |
| queryrequired | string | Search keyword (e.g. 'leather wallet'). |
| sort_on | string | Sort order. Accepted values: most_relevant, lowest_price, highest_price, date_desc. |
| max_price | string | Maximum price filter value. |
| min_price | string | Minimum price filter value. |
| is_vintage | string | Filter vintage items. Accepted values: true, false. |
| is_handmade | string | Filter handmade items. Accepted values: true, false. |
{
"type": "object",
"fields": {
"page": "string, the current page number",
"items": "array of product objects with listing_id, name, url, image, description, price, and currency",
"query": "string, the search keyword used"
},
"sample": {
"data": {
"page": "1",
"items": [
{
"url": "https://www.etsy.com/listing/1214703903/handmade-leather-bifold-wallet",
"name": "Handmade Leather Bifold Wallet: Personalized Front Pocket Card Holder",
"image": "https://i.etsystatic.com/33293494/r/il/6ad75b/3854048691/il_fullxfull.3854048691_hw4l.jpg",
"price": "33.25",
"currency": "USD",
"listing_id": "1214703903",
"description": null
}
],
"query": "leather wallet"
},
"status": "success"
}
}About the Etsy API
Search and Browse Listings
The search_listings endpoint accepts a query string and returns paginated arrays of product objects, each containing listing_id, name, url, image, description, price, and currency. Results can be sorted by most_relevant, lowest_price, highest_price, or date_desc using the sort_on parameter. Optional min_price and max_price filters narrow results by price range, and boolean flags is_vintage and is_handmade target specific item types. The browse_category endpoint covers the same product fields but navigates Etsy's category hierarchy using a category_path string like jewelry/necklaces or clothing/womens-clothing/dresses, with page-based pagination on both endpoints.
Listing Details and Reviews
get_listing_details takes a listing_id (obtainable from search_listings or browse_category results) and returns the full listing record: product title, description, tag array, image URL array, price, currency, views, favorites, badges (e.g. 'Bestseller', 'Top Rated'), and shop_id. That shop_id can be passed directly to get_listing_reviews to retrieve reviews without an additional resolution step. The reviews response distinguishes listing_specific_reviews (filtered to the queried listing) from all_shop_reviews_sample (up to 10 recent shop-wide reviews), so callers get targeted feedback alongside broader shop reputation data.
Shop Discovery and Listings
search_shops accepts a keyword and returns matching shop names and URLs. get_shop_info looks up a shop by its URL slug (e.g. TheBeadChest) and returns name, logo, url, rating, review_count, and shop_id. get_shop_listings pages through a shop's product catalog, returning per-item name, url, image, price, and currency. The shop_id field threads through all three shop-related endpoints and the listing detail endpoint, making it straightforward to chain calls from a shop search through to individual listing reviews.
The Etsy API is a managed, monitored endpoint for etsy.com — not a raw scraper you maintain. Every endpoint is automatically health-checked on a schedule, and when etsy.com changes and a check fails, the API is automatically queued for repair and re-verified. It is built to keep working as the site underneath it changes.
This isn't an official etsy.com API — it's an independent, maintained REST wrapper over public data. Where the source has no official API (or only a limited one), Parse gives you a stable contract over a source that never promised one, and keeps it current. Need a new endpoint or field? You can revise it yourself in plain English and the agent rebuilds it against the live site in minutes — contributing the change back to the shared API is free.
Will this API break when the source site changes?+
Is this an official API from the source site?+
Can I fix or extend this API myself if I need a new endpoint or field?+
What happens if I call an endpoint that has an issue?+
- Price tracking: monitor
priceandcurrencychanges on specificlisting_idvalues over time. - Competitor research: use
get_shop_listingsto catalog a rival shop's full product range and pricing. - Review aggregation: pull
listing_specific_reviewsfromget_listing_reviewsto analyze buyer sentiment for a product. - Category trend analysis: page through
browse_categoryresults to identify popular items in a given niche. - Badge and popularity monitoring: track
badges,views, andfavoritesfromget_listing_detailsto detect rising bestsellers. - Shop discovery: query
search_shopsby keyword to find relevant sellers in a product vertical. - Vintage and handmade filtering: use
is_vintageandis_handmadeflags insearch_listingsto scope research to specific item types.
| Tier | Price | Credits/month | Rate limit |
|---|---|---|---|
| Free | $0/mo | 100 | 5 req/min |
| Hobby | $30/mo | 1,000 | 20 req/min |
| Developer | $100/mo | 5,000 | 100 req/min |
One credit = one API call regardless of which marketplace API you call. Exceeding the rate limit returns a 429 response. Authenticate with the X-API-Key header.
Does Etsy have an official developer API?+
What does `get_listing_reviews` return, and how does listing-specific filtering work?+
listing_specific_reviews, which contains only reviews tied to the queried listing_id, and all_shop_reviews_sample, which contains up to 10 recent reviews across the whole shop. If you already have a shop_id from get_listing_details, pass it directly to skip the internal resolution step.Does the API return seller inventory counts or stock levels?+
get_listing_details response covers price, views, favorites, badges, tags, and images, but does not include quantity available or stock status. You can fork this API on Parse and revise it to add an endpoint targeting that data.How deep does `browse_category` pagination go, and are all Etsy categories supported?+
browse_category endpoint accepts a page integer and a category_path string using forward-slash hierarchy (e.g. clothing/womens-clothing/dresses). It returns the same page of results Etsy serves for that path. Categories that require login or geographic restriction may not return results; there is no built-in endpoint to enumerate all valid category paths. You can fork this API on Parse and revise it to add a category discovery endpoint.Does `search_listings` return seller location or shipping destination data?+
search_listings response includes name, url, image, description, price, currency, and listing_id, but not seller country, shipping origin, or delivery estimates. You can fork this API on Parse and revise it to add those fields if they are available on the listing page.