# Etsy Search Scraper (`astravalabs/etsy-search-scraper`) Actor Scrapes Etsy search results by keyword. Returns listing title, price, shop name, ratings, badges (Bestseller, Star Seller, Etsy's Pick), color variants, shipping info, and ad placement. Supports price range, free shipping, and Star Seller filters. - **URL**: https://apify.com/astravalabs/etsy-search-scraper.md - **Developed by:** [Astrava Labs](https://apify.com/astravalabs) (community) - **Categories:** E-commerce, Lead generation, Developer tools - **Stats:** 3 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks - **User rating**: 5.00 out of 5 stars ## Pricing from $2.00 / 1,000 results This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events. Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-event ## What's an Apify Actor? Actors are a software tools running on the Apify platform, for all kinds of web data extraction and automation use cases. In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours, and optionally produces a well-defined JSON output, datasets with results, or files in key-value store. In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server. Actors are written with capital "A". ## How to integrate an Actor? If asked about integration, you help developers integrate Actors into their projects. You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready. The best way to integrate Actors is as follows. In JavaScript/TypeScript projects, use official [JavaScript/TypeScript client](https://docs.apify.com/api/client/js.md): ```bash npm install apify-client ``` In Python projects, use official [Python client library](https://docs.apify.com/api/client/python.md): ```bash pip install apify-client ``` In shell scripts, use [Apify CLI](https://docs.apify.com/cli/docs.md): ````bash # MacOS / Linux curl -fsSL https://apify.com/install-cli.sh | bash # Windows irm https://apify.com/install-cli.ps1 | iex ```bash In AI frameworks, you might use the [Apify MCP server](https://docs.apify.com/platform/integrations/mcp.md). If your project is in a different language, use the [REST API](https://docs.apify.com/api/v2.md). For usage examples, see the [API](#api) section below. For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt). # README ## Etsy Search Scraper Scrape Etsy search results by keyword and extract 38 fields per listing — pricing, shop metrics, badges, ad placement, product type, color variants, and video — all from a single run. Runs up to 50 keywords in parallel. Each page yields ~64 listings. At full scale (50 keywords × 30 pages), expect around 60,000 listings in under 8 minutes. No proxy setup required. No captcha-solving service needed. Proxies are bundled — just provide keywords and run. **Pricing: ~~$4.00~~ $2.00 per 1,000 listings** — 50% off for a limited time. Platform usage is included — no extra compute charges. ### Quick start ```json { "keywords": ["personalized necklace", "custom mug", "wall art print"], "maxPages": 5, "country": "US" } ```` Three keywords, ~900 listings each, in roughly 30 seconds. ### What you get on every listing **Search context** — the keyword that surfaced the listing, its position in results (`rank`), its organic rank excluding ads (`organic_rank`), and the page it appeared on. **Listing** — `listing_id`, `title`, direct `url`, and `image_url`. **Shop** — `shop_name`, `shop_id`, `shop_url`, star rating (`shop_rating`), total review count (`shop_review_count`), and years on Etsy (`shop_age_years`). **Pricing** — `price`, `currency`, `original_price`, `discount_pct`, `is_on_sale`, `is_free_shipping`. **Ad placement** — `is_ad`, `ad_slot` (position of the sponsored listing on the page). **Badges** — `is_bestseller`, `is_popular_now`, `is_etsys_pick`, `is_star_seller`, `is_limited_stock`. **Product type** — `is_digital`, `has_personalization`. **Media** — `has_video`, `video_url`, `color_variant_count`, `color_variants` (list of color names shown in swatches). **Logistics** — `ships_from`. **Meta** — `total_result_count` (Etsy's total for the keyword), `scraped_at`. ### What you control | Field | Default | Description | |---|---|---| | `keywords` | — | 1–50 search terms, batched in one run | | `maxPages` | 5 | Pages to scrape per keyword (1–30). Pages yield ~64 listings each. | | `country` | US | 22 countries — sets locale, language, and currency | | `sortOrder` | Most relevant | Most relevant, Price low→high, Price high→low, Top reviews, Newest | | `minPrice` | — | Minimum price in the selected country's currency | | `maxPrice` | — | Maximum price in the selected country's currency | | `maxResults` | — | Cap listings per keyword. Leave empty for no cap. | **Filters:** `onSale`, `freeShipping`, `starSeller`, `customizable`, `etsyPick`, `listingType` (all / digital / physical), `excludeSponsored` to drop ads from output. ### Use cases **Niche research.** Run 20 keyword variants in one go, sort by `organic_rank`, see what Etsy's algorithm pushes organically versus what sellers are paying to promote. ```json { "keywords": ["mushroom lamp", "fungi lamp", "cottagecore lamp", "morel lamp"], "maxPages": 10, "excludeSponsored": true } ``` **Competitor ad mapping.** Pull a keyword and filter results where `is_ad: true` — you get every active advertiser with their exact slot position. ```json { "keywords": ["personalized mug"], "maxPages": 5, "sortOrder": "most_relevant" } ``` **Pricing teardowns.** Combine `minPrice` / `maxPrice` with `sortOrder: price_desc` to slice a niche by price tier and see how sellers position across the curve. ```json { "keywords": ["linen dress", "boho dress"], "maxPages": 10, "minPrice": 50, "sortOrder": "price_desc" } ``` **Localized market research.** The same keyword often surfaces an entirely different competitive landscape by country. Run the same terms across US, GB, and DE to compare. ```json { "keywords": ["handmade candle", "soy candle"], "maxPages": 10, "country": "GB" } ``` **Star Seller landscape.** Filter to top-rated shops only and sort by review count to benchmark the most established players in a niche. ```json { "keywords": ["enamel pin"], "maxPages": 15, "starSeller": true, "sortOrder": "highest_reviews" } ``` ### Output Results land in the **default dataset** — export as JSON, CSV, Excel, or JSONL from the Apify console or via API. A run summary lands in the key-value store under `SUMMARY` with per-keyword breakdowns: pages fetched, listing count, and whether Etsy's results were exhausted before `maxPages` was reached. ### Sample row A real listing from a `mug` keyword run — rank 1 organic, 50% off, 21,500 reviews, 10 color variants. ```json { "keyword": "mug", "page": 1, "rank": 3, "organic_rank": 2, "listing_id": "4384679177", "title": "Custom Photo Collage Mug, Your Photo, Your Text, Personalized Photo Mug, Custom Coffee Cup Gift for Family and Friend, Memory Keepsake", "url": "https://www.etsy.com/listing/4384679177/custom-photo-collage-mug-your-photo-your", "image_url": "https://i.etsystatic.com/30637927/r/il/715b79/8042175906/il_1588xN.8042175906_ijkp.jpg", "shop_name": "ArtsifOfficial", "shop_id": 30637927, "shop_url": "https://www.etsy.com/shop/ArtsifOfficial", "shop_rating": 4.9, "shop_review_count": 21500, "shop_age_years": 4.0, "price": 6.99, "currency": "USD", "original_price": 13.99, "discount_pct": 50, "is_on_sale": true, "is_free_shipping": false, "is_ad": false, "ad_slot": null, "is_bestseller": false, "is_popular_now": true, "is_etsys_pick": false, "is_star_seller": false, "is_limited_stock": false, "is_digital": false, "has_personalization": true, "has_video": true, "video_url": "https://v.etsystatic.com/video/upload/ac_none,du_15,q_auto:good/tfadzvtf7adbe63cipsx.mp4", "color_variant_count": 8, "color_variants": ["Green", "Red", "Dark blue", "Purple", "Black", "Yellow", "Light blue", "Pink"], "ships_from": null, "total_result_count": 3061962, "scraped_at": "2026-06-29T21:37:43.489448+00:00" } ``` ### Speed & scale Measured locally, single proxy session per keyword: | Run shape | Time | Listings | |---|---|---| | 1 keyword, 1 page | 5s | 13 | | 1 keyword, 5 pages | 15s | 266 | | 1 keyword, 10 pages | 29s | 582 | | 3 keywords parallel, 3 pages each | 14s | 414 | | 5 keywords parallel, 5 pages each | 18s | 1,324 | | 10 keywords parallel, 5 pages each | 22s | 2,664 | | 50 keywords, 30 pages each (max scale) | 7m 21s | 62,087 | **Why your row count may be below `maxPages × 64`.** Etsy's index caps most keyword searches at around 20–22 pages of results (~1,200–1,400 listings), regardless of how many pages you request. The scraper stops cleanly when Etsy's pagination is exhausted — you won't be charged for empty pages. For broad or trending keywords, `maxPages: 30` is the right ceiling; for niche terms, 10–15 is usually enough. `maxPages` caps at 30. *** > ⚠️ Unofficial. This actor is not affiliated with, endorsed by, or sponsored by Etsy, Inc. "Etsy" is a trademark of Etsy, Inc., used here for descriptive purposes only. # Actor input Schema ## `keywords` (type: `array`): List of search keywords to scrape. ## `maxPages` (type: `integer`): Number of Etsy search result pages to scrape per keyword. Pages yield ~64 listings each. ## `country` (type: `string`): ISO-3166 country code for localized search results and currency. ## `minPrice` (type: `number`): Filter listings to this minimum price (in the selected country's currency). ## `maxPrice` (type: `number`): Filter listings to this maximum price (in the selected country's currency). ## `maxResults` (type: `integer`): Stop collecting listings for a keyword once this many are gathered. Leave empty for no cap. ## `sortOrder` (type: `string`): How to sort the search results. ## `listingType` (type: `string`): Filter by listing type. ## `onSale` (type: `boolean`): Return only discounted / sale listings. ## `freeShipping` (type: `boolean`): Return only listings that offer free shipping. ## `starSeller` (type: `boolean`): Return only listings from Star Seller shops. ## `customizable` (type: `boolean`): Return only listings that accept customization. ## `etsyPick` (type: `boolean`): Return only listings curated by Etsy (merch library). ## `excludeSponsored` (type: `boolean`): Strip ad/sponsored listings from results. Sponsored listings are still fetched but not saved. ## Actor input object example ```json { "keywords": [ "handmade candle" ], "maxPages": 5, "country": "US", "sortOrder": "most_relevant", "listingType": "all", "onSale": false, "freeShipping": false, "starSeller": false, "customizable": false, "etsyPick": false, "excludeSponsored": false } ``` # Actor output Schema ## `results` (type: `string`): Default dataset containing one record per Etsy listing scraped from the search results. # API You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup. ## JavaScript example ```javascript import { ApifyClient } from 'apify-client'; // Initialize the ApifyClient with your Apify API token // Replace the '' with your token const client = new ApifyClient({ token: '', }); // Prepare Actor input const input = { "keywords": [ "handmade candle" ] }; // Run the Actor and wait for it to finish const run = await client.actor("astravalabs/etsy-search-scraper").call(input); // Fetch and print Actor results from the run's dataset (if any) console.log('Results from dataset'); console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`); const { items } = await client.dataset(run.defaultDatasetId).listItems(); items.forEach((item) => { console.dir(item); }); // 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs ``` ## Python example ```python from apify_client import ApifyClient # Initialize the ApifyClient with your Apify API token # Replace '' with your token. client = ApifyClient("") # Prepare the Actor input run_input = { "keywords": ["handmade candle"] } # Run the Actor and wait for it to finish run = client.actor("astravalabs/etsy-search-scraper").call(run_input=run_input) # Fetch and print Actor results from the run's dataset (if there are any) print("💾 Check your data here: https://console.apify.com/storage/datasets/" + run["defaultDatasetId"]) for item in client.dataset(run["defaultDatasetId"]).iterate_items(): print(item) # 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start ``` ## CLI example ```bash echo '{ "keywords": [ "handmade candle" ] }' | apify call astravalabs/etsy-search-scraper --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=astravalabs/etsy-search-scraper", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "Etsy Search Scraper", "description": "Scrapes Etsy search results by keyword. Returns listing title, price, shop name, ratings, badges (Bestseller, Star Seller, Etsy's Pick), color variants, shipping info, and ad placement. Supports price range, free shipping, and Star Seller filters.", "version": "0.0", "x-build-id": "Dh4i4QkChP7CqeJZY" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/astravalabs~etsy-search-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-astravalabs-etsy-search-scraper", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } }, "/acts/astravalabs~etsy-search-scraper/runs": { "post": { "operationId": "runs-sync-astravalabs-etsy-search-scraper", "x-openai-isConsequential": false, "summary": "Executes an Actor and returns information about the initiated run in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/runsResponseSchema" } } } } } } }, "/acts/astravalabs~etsy-search-scraper/run-sync": { "post": { "operationId": "run-sync-astravalabs-etsy-search-scraper", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } } }, "components": { "schemas": { "inputSchema": { "type": "object", "required": [ "keywords" ], "properties": { "keywords": { "title": "Keywords", "minItems": 1, "type": "array", "description": "List of search keywords to scrape.", "items": { "type": "string" } }, "maxPages": { "title": "Max pages per keyword", "minimum": 1, "maximum": 30, "type": "integer", "description": "Number of Etsy search result pages to scrape per keyword. Pages yield ~64 listings each.", "default": 5 }, "country": { "title": "Country", "enum": [ "US", "GB", "CA", "AU", "NZ", "DE", "FR", "IT", "ES", "NL", "IE", "BE", "AT", "PT", "SE", "NO", "DK", "PL", "CH", "CZ", "HU", "RO", "BG", "HR", "JP", "SG", "HK", "IN", "IL", "ZA", "BR", "MX" ], "type": "string", "description": "ISO-3166 country code for localized search results and currency.", "default": "US" }, "minPrice": { "title": "Minimum price", "minimum": 0, "type": "number", "description": "Filter listings to this minimum price (in the selected country's currency)." }, "maxPrice": { "title": "Maximum price", "minimum": 0, "type": "number", "description": "Filter listings to this maximum price (in the selected country's currency)." }, "maxResults": { "title": "Max results per keyword", "minimum": 1, "type": "integer", "description": "Stop collecting listings for a keyword once this many are gathered. Leave empty for no cap." }, "sortOrder": { "title": "Sort order", "enum": [ "most_relevant", "price_asc", "price_desc", "highest_reviews", "date_desc" ], "type": "string", "description": "How to sort the search results.", "default": "most_relevant" }, "listingType": { "title": "Listing type", "enum": [ "all", "digital", "physical" ], "type": "string", "description": "Filter by listing type.", "default": "all" }, "onSale": { "title": "On sale only", "type": "boolean", "description": "Return only discounted / sale listings.", "default": false }, "freeShipping": { "title": "Free shipping only", "type": "boolean", "description": "Return only listings that offer free shipping.", "default": false }, "starSeller": { "title": "Star sellers only", "type": "boolean", "description": "Return only listings from Star Seller shops.", "default": false }, "customizable": { "title": "Customizable only", "type": "boolean", "description": "Return only listings that accept customization.", "default": false }, "etsyPick": { "title": "Etsy's pick only", "type": "boolean", "description": "Return only listings curated by Etsy (merch library).", "default": false }, "excludeSponsored": { "title": "Exclude sponsored listings", "type": "boolean", "description": "Strip ad/sponsored listings from results. Sponsored listings are still fetched but not saved.", "default": false } } }, "runsResponseSchema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "actId": { "type": "string" }, "userId": { "type": "string" }, "startedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "finishedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "status": { "type": "string", "example": "READY" }, "meta": { "type": "object", "properties": { "origin": { "type": "string", "example": "API" }, "userAgent": { "type": "string" } } }, "stats": { "type": "object", "properties": { "inputBodyLen": { "type": "integer", "example": 2000 }, "rebootCount": { "type": "integer", "example": 0 }, "restartCount": { "type": "integer", "example": 0 }, "resurrectCount": { "type": "integer", "example": 0 }, "computeUnits": { "type": "integer", "example": 0 } } }, "options": { "type": "object", "properties": { "build": { "type": "string", "example": "latest" }, "timeoutSecs": { "type": "integer", "example": 300 }, "memoryMbytes": { "type": "integer", "example": 1024 }, "diskMbytes": { "type": "integer", "example": 2048 } } }, "buildId": { "type": "string" }, "defaultKeyValueStoreId": { "type": "string" }, "defaultDatasetId": { "type": "string" }, "defaultRequestQueueId": { "type": "string" }, "buildNumber": { "type": "string", "example": "1.0.0" }, "containerUrl": { "type": "string" }, "usage": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "integer", "example": 1 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } }, "usageTotalUsd": { "type": "number", "example": 0.00005 }, "usageUsd": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "number", "example": 0.00005 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } } } } } } } } } ```