# Etsy Product Search Scraper (`khadinakbar/etsy-product-search-scraper`) Actor Search Etsy product listings by keyword for price monitoring, product discovery, and assortment research. Use for keyword searches onlyโ€”not direct listing pages, shop catalogs, or reviews. Returns price, rating, shop, badges, rank, and URL. $0.005 per result + $0.00005 start. - **URL**: https://apify.com/khadinakbar/etsy-product-search-scraper.md - **Developed by:** [Khadin Akbar](https://apify.com/khadinakbar) (community) - **Categories:** E-commerce, MCP servers, Agents - **Stats:** 1 total users, 1 monthly users, 0.0% runs succeeded, 0 bookmarks - **User rating**: No ratings yet ## Pricing from $5.00 / 1,000 etsy product search results This Actor is paid per event and usage. You are charged both the fixed price for specific events and for Apify platform usage. 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/docs.md): ```bash npm install apify-client ``` In Python projects, use official [Python client library](https://docs.apify.com/api/client/python/docs.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/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 Product Search Scraper Search Etsy product listings by one keyword and receive flat, rank-aware product rows for price monitoring, product discovery, and marketplace research. Use this actor for keyword-based Etsy product search. Do not use it for direct listing-page enrichment, shop catalogs, or customer reviews; use the [Etsy All-in-One Scraper](https://apify.com/khadinakbar/etsy-all-in-one-scraper) for those broader workflows. ### What it returns | Field | Description | | ---------------------------------- | ------------------------------------------------------ | | `listingId`, `listingUrl`, `title` | Stable Etsy listing identity and product title | | `price`, `currency`, `isOnSale` | Search-card price and promotion signals | | `rating`, `reviewCount` | Visible buyer feedback signals when Etsy provides them | | `shopName`, `shopUrl` | Seller identity shown on the search card | | `badges`, `hasFreeShipping` | Recognized Etsy badges and delivery signal | | `dataSource` | `etsySearch` or `searchIndexFallback` provenance | | `searchQuery`, `page`, `position` | Search provenance and rank context | ### Output The default dataset contains one normalized row for each saved Etsy product result. The `OUTPUT` key contains the terminal outcome, result and charge counters, warnings, and a link to that dataset. ### Pricing | Event | Price | | -------------------------- | -----------------------: | | Actor start | $0.00005 per run | | Etsy product search result | $0.005 per saved listing | Platform compute and proxy usage are charged separately through Apify's Pay per event + usage setting. `maxResults` is both the output and result-charge cap: a 50-result run has at most $0.25005 in event charges, plus platform usage. ### Input example ```json { "searchQuery": "handmade necklace", "maxResults": 50, "maxPages": 3 } ```` ### API and MCP use Use the actor when a workflow needs Etsy search-result listings for a single keyword. The actor returns one structured item per product; fetch the default dataset after the run for paginated output. Invalid queries produce an `INVALID_INPUT` run summary; valid queries with no listings produce `VALID_EMPTY`; blocks that leave no useful data fail honestly as `UPSTREAM_FAILED`. ### Limits and data freshness Etsy can change search markup and rate-limit automated traffic. The actor first uses a browser route with residential proxy sessions; if Etsy blocks it, it may return genuine Etsy listing URLs from a public search-index fallback. Fallback rows set unavailable search-card fields to `null` and identify themselves as `dataSource: "searchIndexFallback"`; this actor does not offer destination, sorting, price, sale, or shipping filters. Listing detail data, shop catalog data, and reviews are deliberately outside this actor's contract. ### Legal note Use this actor only for data you are entitled to collect and in compliance with applicable law, Etsy's terms, and your own privacy obligations. # Actor input Schema ## `searchQuery` (type: `string`): Use this when you need Etsy listings for one product phrase. Enter plain keywords such as 'handmade necklace' or 'personalized leather wallet'. The default is 'handmade necklace' and queries may be up to 200 characters. This is not an Etsy listing URL, shop name, or a request for reviews. ## `maxResults` (type: `integer`): Use this to cap the number of Etsy listing rows returned and billed. Enter an integer from 1 to 250; for example, 50. Defaults to 50 and each saved result is charged at $0.005. This is not a page count and cannot exceed the actor's safety limit. ## `maxPages` (type: `integer`): Use this to limit Etsy result pages inspected for the query. Enter an integer from 1 to 10; for example, 3. Defaults to 3, while maxResults remains the final result and billing cap. This is not an exact number of listings because page sizes vary. ## Actor input object example ```json { "searchQuery": "personalized leather wallet", "maxResults": 50, "maxPages": 3 } ``` # Actor output Schema ## `dataset` (type: `string`): Default dataset containing normalized Etsy product-search listings, including listing URL, title, available search-card fields, provenance, and rank. ## `summary` (type: `string`): Terminal outcome with result and billing counters, retrieval warnings, and the default dataset URL. ## `runSummary` (type: `string`): Duplicate machine-readable terminal summary for monitoring systems that use a distinct operational key. # 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 = { "searchQuery": "handmade necklace", "maxResults": 25, "maxPages": 2 }; // Run the Actor and wait for it to finish const run = await client.actor("khadinakbar/etsy-product-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 = { "searchQuery": "handmade necklace", "maxResults": 25, "maxPages": 2, } # Run the Actor and wait for it to finish run = client.actor("khadinakbar/etsy-product-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 '{ "searchQuery": "handmade necklace", "maxResults": 25, "maxPages": 2 }' | apify call khadinakbar/etsy-product-search-scraper --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=khadinakbar/etsy-product-search-scraper", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "Etsy Product Search Scraper", "description": "Search Etsy product listings by keyword for price monitoring, product discovery, and assortment research. Use for keyword searches onlyโ€”not direct listing pages, shop catalogs, or reviews. Returns price, rating, shop, badges, rank, and URL. $0.005 per result + $0.00005 start.", "version": "0.4", "x-build-id": "ShmXcrDNSZ36zBvjI" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/khadinakbar~etsy-product-search-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-khadinakbar-etsy-product-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/khadinakbar~etsy-product-search-scraper/runs": { "post": { "operationId": "runs-sync-khadinakbar-etsy-product-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/khadinakbar~etsy-product-search-scraper/run-sync": { "post": { "operationId": "run-sync-khadinakbar-etsy-product-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": [ "searchQuery" ], "properties": { "searchQuery": { "title": "Etsy product search query", "maxLength": 200, "type": "string", "description": "Use this when you need Etsy listings for one product phrase. Enter plain keywords such as 'handmade necklace' or 'personalized leather wallet'. The default is 'handmade necklace' and queries may be up to 200 characters. This is not an Etsy listing URL, shop name, or a request for reviews.", "default": "handmade necklace" }, "maxResults": { "title": "Maximum product results", "minimum": 1, "maximum": 250, "type": "integer", "description": "Use this to cap the number of Etsy listing rows returned and billed. Enter an integer from 1 to 250; for example, 50. Defaults to 50 and each saved result is charged at $0.005. This is not a page count and cannot exceed the actor's safety limit.", "default": 50 }, "maxPages": { "title": "Maximum search pages", "minimum": 1, "maximum": 10, "type": "integer", "description": "Use this to limit Etsy result pages inspected for the query. Enter an integer from 1 to 10; for example, 3. Defaults to 3, while maxResults remains the final result and billing cap. This is not an exact number of listings because page sizes vary.", "default": 3 } } }, "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 } } } } } } } } } } ```