--- type: "firecrawl-provider" description: "Etsy marketplace listings: listing details and prices, per-variation pricing, similar listings, shop sections and search query suggestions from Etsy's public ajax JSON API. Keyword search, shop listing enumeration and reviews are DataDome-gated and not available." use_when: "Etsy marketplace listings: listing details and prices, per-variation pricing, similar listings, shop sections and search query suggestions from Etsy's public ajax JSON API. Keyword search, shop listing enumeration and reviews are DataDome-gated and not available." categories: "Retail" capabilities: 5 credits_per_call: 5 --- # Etsy on Firecrawl Alexandria Etsy marketplace listings: listing details and prices, per-variation pricing, similar listings, shop sections and search query suggestions from Etsy's public ajax JSON API. Keyword search, shop listing enumeration and reviews are DataDome-gated and not available. - Categories: Retail - Category index: [Retail category](https://firecrawl.dev/alexandria/agents/categories/retail) - Provider key: `etsy-com` - Access: Firecrawl credits - Cost: 5 credits per call ## More - [Human guide](https://firecrawl.dev/app/alexandria/etsy-com) - [OpenAPI spec](https://firecrawl.dev/alexandria/agents/providers/etsy-com/openapi.json) ## Capabilities - [Listing](https://firecrawl.dev/alexandria/agents/providers/etsy-com/listings/listing): One Etsy listing by id or listing URL: title, description, state and availability, price in the requested currency (USD, GBP or EUR) plus the USD price, quantity, tags, materials, images, category (taxonomy node), shop identity and ships-from country. - [Listing variations](https://firecrawl.dev/alexandria/agents/providers/etsy-com/listings/listing_variations): Variation properties of a listing (for example size or finish) with each value's availability and its price and price difference in the requested currency. An empty properties list means the listing has no variations. - [Search suggestions](https://firecrawl.dev/alexandria/agents/providers/etsy-com/listings/search_suggestions): Etsy's search-box query completions for a text prefix or phrase, with the simplified query terms Etsy derived. Returns query strings, not listings. - [Shop sections](https://firecrawl.dev/alexandria/agents/providers/etsy-com/listings/shop_sections): The sections (custom categories) of an Etsy shop with each section's active listing count and display rank. An empty list means the shop has no sections. Listing enumeration per section is DataDome-gated and not available. - [Similar listings](https://firecrawl.dev/alexandria/agents/providers/etsy-com/listings/similar_listings): Listings Etsy recommends as similar to a seed listing: up to `limit` listing cards with title, URL, price, state, shop and primary image. The only discovery surface reachable without a browser session; results are recommendation-driven and vary between calls. No pagination (the API ignores offsets). ## 1. Choose this provider when Etsy marketplace listings: listing details and prices, per-variation pricing, similar listings, shop sections and search query suggestions from Etsy's public ajax JSON API. Keyword search, shop listing enumeration and reviews are DataDome-gated and not available. ## 2. Minimal request Call `POST https://api.firecrawl.dev/v2/scrape` with `{ alexandria: { provider, capability, options } }`. For a batch, send `{ alexandria: [...] }` with up to 10 calls. ```json { "provider": "etsy-com", "capability": "listings/listing", "options": { "listing_id": 1442569696 } } ``` ## 3. Add provider options Use only the options needed for the task: - `currency` (string): Currency the listing price is returned in (Etsy's x-detected-locale). price_usd is always returned as well. Example: `USD` - `listing_id` (number): Numeric Etsy listing id (the number after /listing/ in a listing URL). Example: `10` - `url` (string): An etsy.com listing URL: https://www.etsy.com/listing/{id}/..., a regional /uk/listing/{id}/ form or a {shop}.etsy.com/listing/{id} storefront URL. Example: `` ## 4. Request through your preferred interface ### JavaScript ```javascript const result = await firecrawl.scrape({ alexandria: { provider: "etsy-com", capability: "listings/listing", options: { listing_id: 1442569696, }, }, }); ``` ### Python ```python result = firecrawl.scrape_alexandria({ "provider": "etsy-com", "capability": "listings/listing", "options": { "listing_id": 1442569696 } }) ``` ### cURL ```sh curl https://api.firecrawl.dev/v2/scrape \ -H "Authorization: Bearer $FIRECRAWL_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "alexandria": { "provider": "etsy-com", "capability": "listings/listing", "options": { "listing_id": 1442569696 } } }' ``` ### CLI ```sh firecrawl scrape 'etsy-com/listings/listing' \ --options '{"listing_id":1442569696}' ``` ### MCP Call the FCX MCP retrieve tool with this object: ```json { "provider": "etsy-com", "capability": "listings/listing", "options": { "listing_id": 1442569696 } } ``` Ask for only the returned fields needed by the task. ## 5. Full request shape ```json { "provider": "etsy-com", "capability": "listings/listing", "options": { "listing_id": 1442569696 } } ``` ## 6. Response data The response includes `success`, `provider`, `capability`, `creditsCost` and `data`. This example shows the provider payload in `data`: ```json { "category": { "full_path_taxonomy_ids": [ 891, 1031, 1054, 1862 ], "level": 3, "name": "Drinkware", "path": "home_and_living.kitchen_and_dining.drink_and_barware.drinkware", "taxonomy_id": 1862 }, "created_at": 1782096093, "currency": "USD", "description": "Perfect glass for iced coffees, iced teas, sodas or any beverage. \n20 oz Beer Can Glass", "favorites": 0, "has_variation_pricing": false, "image_count": 1, "images": [ { "height": 3000, "image_id": 4798486416, "url": "https://i.etsystatic.com/38814377/r/il/4ec0bd/4798486416/il_fullxfull.4798486416_gd73.jpg", "width": 2250 } ], "is_available": true, "is_bestseller": false, "is_customizable": false, "is_digital": false, "is_made_to_order": false, "is_on_vacation": false, "is_sold_out": false, "language": "en-US", "listing_id": 1442569696, "materials": [ "Glass" ], "observed_at_ms": 1789767406278, "price": { "amount": "15.00", "amount_minor": 1500, "currency": "USD", "formatted": "$15.00" }, "price_usd_minor": 1500, "quantity": 1, "ships_from_country": "US", "shop": { "avatar_url": "https://i.etsystatic.com/iusa/664aed/96706734/iusa_75x75.96706734_oe94.jpg?version=0", "section_id": null, "section_name": null, "shop_id": 38814377, "shop_name": "AMGDesignsNC", "user_id": 703590372 }, "shop_subdomain_url": "https://amgdesignsnc.etsy.com/listing/1442569696", "state": "active", "tags": [ "Bride To Be", "Beer Can Glass", "Iced Coffee Glass" ], "title": "Bride To Be, Iced Coffee Glass, Beer Can Glass, Coffee Glass,", "updated_at": 1782096093, "url": "https://www.etsy.com/listing/1442569696/bride-to-be-iced-coffee-glass-beer-can", "views": 0, "when_made": "2020,2023" } ``` ## API reference-derived contract The following capability contract is generated from the same normalized Alexandria API reference exposed in the API spec. ### Listing - Capability: `listings/listing` - Description: One Etsy listing by id or listing URL: title, description, state and availability, price in the requested currency (USD, GBP or EUR) plus the USD price, quantity, tags, materials, images, category (taxonomy node), shop identity and ships-from country. - Instructions: You have a listing id or an etsy.com/listing/{id}/ URL. Use similar_listings for discovery, listing_variations for option prices, shop_sections for the seller's sections. - Cost: 5 credits per call - Capability file: [Listing](https://firecrawl.dev/alexandria/agents/providers/etsy-com/listings/listing) Accepted options: - `currency` (string): Currency the listing price is returned in (Etsy's x-detected-locale). price_usd is always returned as well. Example: `USD` - `listing_id` (number): Numeric Etsy listing id (the number after /listing/ in a listing URL). Example: `10` - `url` (string): An etsy.com listing URL: https://www.etsy.com/listing/{id}/..., a regional /uk/listing/{id}/ form or a {shop}.etsy.com/listing/{id} storefront URL. Example: `` Response schema example: ```json { "category": { "full_path_taxonomy_ids": [ 891, 1031, 1054, 1862 ], "level": 3, "name": "Drinkware", "path": "home_and_living.kitchen_and_dining.drink_and_barware.drinkware", "taxonomy_id": 1862 }, "created_at": 1782096093, "currency": "USD", "description": "Perfect glass for iced coffees, iced teas, sodas or any beverage. \n20 oz Beer Can Glass", "favorites": 0, "has_variation_pricing": false, "image_count": 1, "images": [ { "height": 3000, "image_id": 4798486416, "url": "https://i.etsystatic.com/38814377/r/il/4ec0bd/4798486416/il_fullxfull.4798486416_gd73.jpg", "width": 2250 } ], "is_available": true, "is_bestseller": false, "is_customizable": false, "is_digital": false, "is_made_to_order": false, "is_on_vacation": false, "is_sold_out": false, "language": "en-US", "listing_id": 1442569696, "materials": [ "Glass" ], "observed_at_ms": 1789767406278, "price": { "amount": "15.00", "amount_minor": 1500, "currency": "USD", "formatted": "$15.00" }, "price_usd_minor": 1500, "quantity": 1, "ships_from_country": "US", "shop": { "avatar_url": "https://i.etsystatic.com/iusa/664aed/96706734/iusa_75x75.96706734_oe94.jpg?version=0", "section_id": null, "section_name": null, "shop_id": 38814377, "shop_name": "AMGDesignsNC", "user_id": 703590372 }, "shop_subdomain_url": "https://amgdesignsnc.etsy.com/listing/1442569696", "state": "active", "tags": [ "Bride To Be", "Beer Can Glass", "Iced Coffee Glass" ], "title": "Bride To Be, Iced Coffee Glass, Beer Can Glass, Coffee Glass,", "updated_at": 1782096093, "url": "https://www.etsy.com/listing/1442569696/bride-to-be-iced-coffee-glass-beer-can", "views": 0, "when_made": "2020,2023" } ``` ### Listing variations - Capability: `listings/listing_variations` - Description: Variation properties of a listing (for example size or finish) with each value's availability and its price and price difference in the requested currency. An empty properties list means the listing has no variations. - Instructions: A listing shows has_variation_pricing or you need the option values a buyer can pick. Needs a listing id from listing or similar_listings. - Cost: 5 credits per call - Capability file: [Listing variations](https://firecrawl.dev/alexandria/agents/providers/etsy-com/listings/listing_variations) Accepted options: - `currency` (string): currency Example: `USD` - `listing_id` (number, required): listing_id Example: `10` Response schema example: ```json { "currency": "USD", "listing_id": 1582028184, "observed_at_ms": 1789767410794, "properties": [ { "name": "Lid type finish", "property_id": 513, "type": "ListingMetadata_Variation_Custom1", "values": [ { "image_id": null, "is_available": true, "listing_variation_id": 3986098762, "price": { "amount": "27.00", "amount_minor": 2700, "currency": "USD", "formatted": "$27.00" }, "price_diff": { "amount": "4.00", "amount_minor": 400, "currency": "USD", "formatted": "$4.00" }, "value": "W/rhinestones", "value_id": 117815404815 }, { "image_id": null, "is_available": true, "listing_variation_id": 4004887627, "price": { "amount": "23.00", "amount_minor": 2300, "currency": "USD", "formatted": "$23.00" }, "price_diff": { "amount": "0.00", "amount_minor": 0, "currency": "USD", "formatted": "$0.00" }, "value": "no rhinestones", "value_id": 109757542838 } ] } ], "property_count": 1, "url": "https://www.etsy.com/listing/1582028184/" } ``` ### Search suggestions - Capability: `listings/search_suggestions` - Description: Etsy's search-box query completions for a text prefix or phrase, with the simplified query terms Etsy derived. Returns query strings, not listings. - Instructions: Expand or normalize a shopping query before looking for listings elsewhere. Keyword search itself is not available from this program. - Cost: 5 credits per call - Capability file: [Search suggestions](https://firecrawl.dev/alexandria/agents/providers/etsy-com/listings/search_suggestions) Accepted options: - `query` (string, required): Search text; must contain a non-whitespace character. Example: `` Response schema example: ```json { "count": 11, "observed_at_ms": 1789767421762, "query": "ceramic mug", "simplified_queries": [ "ceramic", "mug" ], "suggestions": [ { "categories": [], "query": "ceramic mug", "search_url": "https://www.etsy.com/search?q=ceramic+mug" }, { "categories": [], "query": "ceramic mug handmade", "search_url": "https://www.etsy.com/search?q=ceramic+mug+handmade" }, { "categories": [], "query": "ceramic mug with lid", "search_url": "https://www.etsy.com/search?q=ceramic+mug+with+lid" }, { "categories": [], "query": "ceramic mug set", "search_url": "https://www.etsy.com/search?q=ceramic+mug+set" }, { "categories": [], "query": "ceramic mug with sip hole", "search_url": "https://www.etsy.com/search?q=ceramic+mug+with+sip+hole" }, { "categories": [], "query": "ceramic mug template", "search_url": "https://www.etsy.com/search?q=ceramic+mug+template" }, { "categories": [], "query": "ceramic mug travel", "search_url": "https://www.etsy.com/search?q=ceramic+mug+travel" }, { "categories": [], "query": "ceramic mug cat", "search_url": "https://www.etsy.com/search?q=ceramic+mug+cat" }, { "categories": [], "query": "ceramic mug face", "search_url": "https://www.etsy.com/search?q=ceramic+mug+face" }, { "categories": [], "query": "ceramic mug floral", "search_url": "https://www.etsy.com/search?q=ceramic+mug+floral" }, { "categories": [], "query": "ceramic mugs personalized", "search_url": "https://www.etsy.com/search?q=ceramic+mugs+personalized" } ] } ``` ### Shop sections - Capability: `listings/shop_sections` - Description: The sections (custom categories) of an Etsy shop with each section's active listing count and display rank. An empty list means the shop has no sections. Listing enumeration per section is DataDome-gated and not available. - Instructions: You have a shop_id from a listing and want the shop's catalog structure and active listing counts. - Cost: 5 credits per call - Capability file: [Shop sections](https://firecrawl.dev/alexandria/agents/providers/etsy-com/listings/shop_sections) Accepted options: - `shop_id` (number, required): Numeric Etsy shop id (listing.shop.shop_id). Example: `10` Response schema example: ```json { "active_listing_total": 69, "count": 4, "observed_at_ms": 1789767418287, "sections": [ { "active_listing_count": 38, "rank": 2, "section_id": 39995785, "title": "Earrings" }, { "active_listing_count": 19, "rank": 3, "section_id": 38145371, "title": "Libbey Glasses" }, { "active_listing_count": 10, "rank": 4, "section_id": 38232547, "title": "20 oz Tumblers" }, { "active_listing_count": 2, "rank": 5, "section_id": 38180679, "title": "Mental Health T-Shirts" } ], "shop_id": 24992764 } ``` ### Similar listings - Capability: `listings/similar_listings` - Description: Listings Etsy recommends as similar to a seed listing: up to `limit` listing cards with title, URL, price, state, shop and primary image. The only discovery surface reachable without a browser session; results are recommendation-driven and vary between calls. No pagination (the API ignores offsets). - Instructions: Fan out from one known listing to related listings. Etsy keyword search is DataDome-gated and not available; use search_suggestions for query completions. - Cost: 5 credits per call - Capability file: [Similar listings](https://firecrawl.dev/alexandria/agents/providers/etsy-com/listings/similar_listings) Accepted options: - `currency` (string): currency Example: `USD` - `limit` (number): Maximum number of listings to return. Example: `12` - `listing_id` (number, required): Seed listing id. Example: `10` Response schema example: ```json { "count": 3, "currency": "USD", "listings": [ { "category_path": "home_and_living.kitchen_and_dining.drink_and_barware.drinkware", "favorites": 0, "has_variation_pricing": false, "image_url": "https://i.etsystatic.com/38814377/r/il/4d7354/4846729565/il_fullxfull.4846729565_4mbl.jpg", "is_available": true, "is_bestseller": false, "is_digital": false, "is_on_vacation": false, "is_sold_out": false, "listing_id": 1442564560, "price": { "amount": "15.00", "amount_minor": 1500, "currency": "USD", "formatted": "$15.00" }, "price_usd_minor": 1500, "shop": { "shop_id": 38814377, "shop_name": "AMGDesignsNC" }, "state": "active", "title": "Coffee Glass, Iced Coffee Glass, Beer Can Glass, Coffee Coffee Coffee, Coffee Glass Can", "url": "https://www.etsy.com/listing/1442564560/coffee-glass-iced-coffee-glass-beer-can" }, { "category_path": "home_and_living.kitchen_and_dining.drink_and_barware.drinkware.tumblers_and_water_glasses", "favorites": 1, "has_variation_pricing": false, "image_url": "https://i.etsystatic.com/38814377/r/il/98b9b6/4846706763/il_fullxfull.4846706763_jodc.jpg", "is_available": true, "is_bestseller": false, "is_digital": false, "is_on_vacation": false, "is_sold_out": false, "listing_id": 1456762025, "price": { "amount": "15.00", "amount_minor": 1500, "currency": "USD", "formatted": "$15.00" }, "price_usd_minor": 1500, "shop": { "shop_id": 38814377, "shop_name": "AMGDesignsNC" }, "state": "active", "title": "Howdy Glass, Iced Coffee Glass, Beer Can Glass, Coffee Cup,", "url": "https://www.etsy.com/listing/1456762025/howdy-glass-iced-coffee-glass-beer-can" }, { "category_path": "home_and_living.kitchen_and_dining.drink_and_barware.drinkware.tumblers_and_water_glasses", "favorites": 1, "has_variation_pricing": false, "image_url": "https://i.etsystatic.com/38814377/r/il/27a63c/4798460454/il_fullxfull.4798460454_qon7.jpg", "is_available": true, "is_bestseller": false, "is_digital": false, "is_on_vacation": false, "is_sold_out": false, "listing_id": 1442562716, "price": { "amount": "15.00", "amount_minor": 1500, "currency": "USD", "formatted": "$15.00" }, "price_usd_minor": 1500, "shop": { "shop_id": 38814377, "shop_name": "AMGDesignsNC" }, "state": "active", "title": "Heart Coffee Cup, Iced Coffee Glass, Beer Can Glass, Coffee Cup", "url": "https://www.etsy.com/listing/1442562716/heart-coffee-cup-iced-coffee-glass-beer" } ], "observed_at_ms": 1789767414592, "seed_listing_id": 1442569696 } ```