# Etsy Shop Details Scraper (`khadinakbar/etsy-shop-details-scraper`) Actor Extract public Etsy shop profiles by URL or shop name. Returns seller identity, ratings, reviews, catalog size, location, branding, and provenance as flat, MCP-ready JSON. - **URL**: https://apify.com/khadinakbar/etsy-shop-details-scraper.md - **Developed by:** [Khadin Akbar](https://apify.com/khadinakbar) (community) - **Categories:** E-commerce, MCP servers, Automation - **Stats:** 1 total users, 1 monthly users, 0.0% runs succeeded, 0 bookmarks - **User rating**: No ratings yet ## Pricing from $15.00 / 1,000 etsy shop profile extracteds 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 Shop Details Scraper Extract clean, structured public profiles for known Etsy shops. Provide Etsy shop URLs, exact shop names, or both and receive one validated JSON record per matched shop with seller identity, public description, owner, location, rating, review count, active-listing count, branding, and collection provenance. Use this Actor for competitor research, seller enrichment, supplier shortlists, catalog monitoring, and AI-agent workflows that begin with a known Etsy seller. Do not use it for product keyword search, individual listing details, or customer reviews; use `khadinakbar/etsy-all-in-one-scraper` for those broader jobs. ### What changed in version 0.2 The earlier implementation tried Etsy's public shop page first. Etsy returned a DataDome challenge to that route in cloud runs, so every useful request paid the latency and residential-proxy cost of a guaranteed 403 before starting a separate fallback Actor. Bulk input also launched the fallback serially, one cold start per shop. Version 0.2 removes that dead route. It now runs focused rich-profile lookups concurrently, validates only `recordType: "shop"` records, derives a location only when the public description explicitly says “located in …,” and uses a second mobile-API route only when the primary profile is missing or incomplete. The result is faster, cheaper, more honest, and more reliable. Missing values remain `null`; the Actor never turns unavailable sections into a fake empty list or invents a sales estimate. ### Output fields | Field | Meaning | | --- | --- | | `shop_id`, `shop_name`, `shop_url` | Canonical public Etsy shop identity | | `title`, `description`, `shop_slogan` | Public profile copy when available | | `shop_owner`, `shop_location` | Public seller name and location when exposed | | `shop_rating`, `shop_review_count` | Aggregate public reputation metrics | | `total_active_listings` | Current public catalog size when available | | `total_sales_count` | Lifetime sales only if an upstream route publishes it; otherwise `null` | | `is_star_seller`, `on_etsy_since` | Mobile-route badge and opening year when available | | `shop_logo_url`, `shop_banner_url` | Public branding image URLs | | `shop_sections` | Public section names when requested and exposed; otherwise `null` | | `source`, `data_sources` | Exact collection route or merged provider evidence | | `source_url`, `scraped_at` | Canonical lookup URL and ISO 8601 normalization time | Every row uses a stable, flat shape suitable for Apify MCP, JSON, CSV, spreadsheets, warehouses, and LLM tool calls. Optional values are explicit `null`s rather than omitted keys. ### Input #### Lookup by URL ```json { "shopUrls": [ { "url": "https://www.etsy.com/shop/HunchbackLeather" }, { "url": "https://www.etsy.com/shop/LindyLonghurst" } ], "maxShops": 2, "includeShopSections": true } ```` #### Lookup by exact shop name ```json { "shopNames": ["HunchbackLeather", "LindyLonghurst"], "maxShops": 2 } ``` You may combine `shopUrls` and `shopNames`. Inputs are canonicalized and deduplicated case-insensitively before the `maxShops` cap is applied. A valid Etsy shop handle starts with a letter or number and may contain letters, numbers, or hyphens. `maxShops` defaults to 10 and cannot exceed 100. It is the hard ceiling for stored and billed shop-profile rows. The legacy `proxyConfiguration` field remains visible so old saved tasks continue to run, but version 0.2 uses managed provider routes and ignores that legacy setting. ### Output example ```json { "record_type": "shop", "shop_id": "34829689", "shop_name": "HunchbackLeather", "shop_url": "https://www.etsy.com/shop/HunchbackLeather", "title": "HunchbackLeather", "description": "Shop Handmade leather goods from our Indiana shop, USA by HunchbackLeather located in Goshen, Indiana.", "shop_owner": "Randy Johnson", "shop_location": "Goshen, Indiana", "shop_rating": 5, "shop_review_count": 483, "total_sales_count": null, "total_active_listings": 19, "is_star_seller": null, "on_etsy_since": null, "shop_logo_url": "https://i.etsystatic.com/34829689/r/isla/example.jpg", "shop_banner_url": null, "shop_slogan": "Handmade leather goods from our Indiana shop, USA", "shop_sections": null, "source_url": "https://www.etsy.com/shop/HunchbackLeather", "source": "cirkit_profile", "data_sources": ["cirkit_profile"], "scraped_at": "2026-07-18T00:00:00.000Z" } ``` ### Pricing and cost controls - `$0.015` for each validated shop profile stored in the default dataset - `$0.00005` Actor-start event - Apify platform usage is passed through separately Before collection begins, the log and status message show the maximum possible shop-detail event charge. Ten requested shops therefore cap this Actor's shop-detail events at `$0.150`. A row is normalized and validated before it is written and billed through the same Apify SDK call. Invalid input, nonexistent shops, blocked routes, and rejected records do not trigger a `shop-detail` event. The Actor stops writing as soon as `maxShops` or the caller's Apify charge limit is reached. `OUTPUT` and `RUN_SUMMARY` report the number of stored profiles, logical billed-event count, provider runs, warnings, and whether a charge cap stopped the run. ### Terminal outcomes Every run writes both `OUTPUT` and `RUN_SUMMARY` and uses one explicit outcome: - `COMPLETE`: all matched profiles were stored. - `PARTIAL`: at least one useful profile was stored, but another target or write failed. - `VALID_EMPTY`: the inputs were valid, the routes ran, but no public shops matched. - `INVALID_INPUT`: no valid Etsy shop URL or name was supplied; the message includes a working example. - `UPSTREAM_FAILED`: every required route failed before any useful row could be returned. - `CONFIG_ERROR`: deployment or runtime configuration prevented the Actor from operating. User-correctable input and genuine empty results finish successfully. Required-provider and configuration outages fail honestly rather than hiding an outage behind a green run with an empty dataset. ### Reliability and data quality The primary route is optimized for Etsy shop profiles and returns descriptions, ownership, ratings, reviews, listing counts, and branding. Requests run concurrently with a bounded worker pool, so batches avoid the former one-shop-at-a-time bottleneck. When a primary record is absent or lacks location or catalog-size evidence, a mobile-API fallback is queried and merged by canonical shop name. The Actor ignores listing-card rows returned alongside a profile. It never charges those rows, and they never enter this Actor's dataset. Complete candidates pass code-level validation that mirrors the dataset schema before persistence. Provider failures, validation failures, and storage failures are counted separately in `RUN_SUMMARY`. Etsy may close, rename, suspend, or hide a shop. In those cases the Actor returns `VALID_EMPTY` when functioning routes agree that no public profile exists. Check spelling and current shop status before retrying. A transient provider outage is reported separately as `UPSTREAM_FAILED` only when every available route fails. ### AI-agent guidance Use this tool when the agent already has an Etsy shop name or shop URL and needs structured seller-profile facts. Good requests include “compare the ratings, review counts, and active listings of these Etsy shops,” “enrich this supplier list with Etsy owner and location,” and “monitor catalog-size changes for these sellers.” Do not use this tool for broad Etsy product discovery, listing prices, listing descriptions, or review text. It returns one compact record per shop and costs `$0.015` per stored profile plus platform usage. ### API example ```bash curl -X POST "https://api.apify.com/v2/acts/khadinakbar~etsy-shop-details-scraper/runs" \ -H "Authorization: Bearer $APIFY_TOKEN" \ -H "Content-Type: application/json" \ -d '{"shopNames":["HunchbackLeather"],"maxShops":1}' ``` Never place an Apify token in a URL or commit it to source control. ### Related Etsy Actors - [`khadinakbar/etsy-all-in-one-scraper`](https://apify.com/khadinakbar/etsy-all-in-one-scraper) for mixed listing, product, shop-catalog, and review workflows - [`khadinakbar/etsy-listings-scraper`](https://apify.com/khadinakbar/etsy-listings-scraper) for Etsy listing search results and direct listing URLs - [`khadinakbar/etsy-reviews-scraper`](https://apify.com/khadinakbar/etsy-reviews-scraper) for structured customer-review records - [`khadinakbar/etsy-product-search-scraper`](https://apify.com/khadinakbar/etsy-product-search-scraper) for keyword-led Etsy product discovery ### FAQ #### Can I integrate this with the Apify API? Yes. Start runs through the REST API, JavaScript client, Python client, schedules, webhooks, or integrations. The default dataset contains shop rows; `OUTPUT` and `RUN_SUMMARY` are in the run's default key-value store. #### Can an AI agent call it through MCP? Yes. Add `khadinakbar/etsy-shop-details-scraper` to the Apify MCP server, call it with exact shop names or URLs, then read the default dataset. The flat nullable schema is designed to be predictable for LLM tool consumers. #### Why is a field null? Etsy and the active provider routes do not expose every profile field for every seller. A null means unavailable, not zero. In particular, the Actor never estimates lifetime sales or fabricates shop sections. #### Is it legal to scrape public Etsy shop data? Public accessibility does not remove your compliance obligations. Review Etsy's terms, applicable privacy and database laws, your purpose, and your retention practices. Obtain professional advice for regulated or high-risk use cases. ### Legal and responsible use This Actor collects publicly accessible Etsy shop metadata. You are responsible for complying with Etsy's terms, applicable law, contractual restrictions, and your own privacy and retention obligations. Do not use the output for harassment, discrimination, unauthorized profiling, or attempts to access private seller information. ### Your feedback If a public shop returns incomplete or stale data, open an Apify issue with the shop URL and run ID. Do not include private credentials, cookies, or personal data in the report. # Actor input Schema ## `shopUrls` (type: `array`): Use this when you have full Etsy shop URLs. Each item must look like https://www.etsy.com/shop/HunchbackLeather. URLs are deduplicated case-insensitively and combined with shopNames. Do not provide Etsy listing, search, or review URLs here. ## `shopNames` (type: `array`): Use this when you know Etsy shop handles instead of URLs. Enter values such as HunchbackLeather, without spaces or an @ prefix. Names are combined with shopUrls and deduplicated. Do not enter product keywords; this field performs exact shop lookup only. ## `maxShops` (type: `integer`): Use this to cap the number of shop profiles processed and billed. One successfully stored profile costs $0.015, so 10 shops cap shop-detail events at $0.15. The default is 10 and the hard maximum is 100. This limit does not represent product listings per shop. ## `includeShopSections` (type: `boolean`): Use this to include public shop-section names when an upstream route exposes them. The default is true; unavailable sections remain null instead of becoming a fabricated empty list. Set false for the leanest profile shape. This does not fetch products inside each section. ## `proxyConfiguration` (type: `object`): Kept for backward compatibility with saved tasks created before version 0.2. The rebuilt actor uses managed provider routes and does not send this configuration to Etsy. Leave the default unchanged. This field does not select the provider or country of returned shop metadata. ## Actor input object example ```json { "shopUrls": [ { "url": "https://www.etsy.com/shop/HunchbackLeather" } ], "shopNames": [ "HunchbackLeather", "LindyLonghurst" ], "maxShops": 25, "includeShopSections": true, "proxyConfiguration": { "useApifyProxy": true } } ``` # Actor output Schema ## `shops` (type: `string`): No description ## `summary` (type: `string`): No description ## `runSummary` (type: `string`): No description # 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 = { "shopUrls": [ { "url": "https://www.etsy.com/shop/HunchbackLeather" } ], "maxShops": 1, "includeShopSections": true, "proxyConfiguration": { "useApifyProxy": true } }; // Run the Actor and wait for it to finish const run = await client.actor("khadinakbar/etsy-shop-details-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 = { "shopUrls": [{ "url": "https://www.etsy.com/shop/HunchbackLeather" }], "maxShops": 1, "includeShopSections": True, "proxyConfiguration": { "useApifyProxy": True }, } # Run the Actor and wait for it to finish run = client.actor("khadinakbar/etsy-shop-details-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 '{ "shopUrls": [ { "url": "https://www.etsy.com/shop/HunchbackLeather" } ], "maxShops": 1, "includeShopSections": true, "proxyConfiguration": { "useApifyProxy": true } }' | apify call khadinakbar/etsy-shop-details-scraper --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=khadinakbar/etsy-shop-details-scraper", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "Etsy Shop Details Scraper", "description": "Extract public Etsy shop profiles by URL or shop name. Returns seller identity, ratings, reviews, catalog size, location, branding, and provenance as flat, MCP-ready JSON.", "version": "0.2", "x-build-id": "1PjJnnZOTqppDrxqu" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/khadinakbar~etsy-shop-details-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-khadinakbar-etsy-shop-details-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-shop-details-scraper/runs": { "post": { "operationId": "runs-sync-khadinakbar-etsy-shop-details-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-shop-details-scraper/run-sync": { "post": { "operationId": "run-sync-khadinakbar-etsy-shop-details-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", "properties": { "shopUrls": { "title": "Etsy shop URLs", "type": "array", "description": "Use this when you have full Etsy shop URLs. Each item must look like https://www.etsy.com/shop/HunchbackLeather. URLs are deduplicated case-insensitively and combined with shopNames. Do not provide Etsy listing, search, or review URLs here.", "items": { "type": "object", "properties": { "url": { "title": "Shop URL", "description": "A full Etsy shop profile URL, for example https://www.etsy.com/shop/HunchbackLeather.", "type": "string" } }, "required": [ "url" ] }, "default": [] }, "shopNames": { "title": "Etsy shop names", "type": "array", "description": "Use this when you know Etsy shop handles instead of URLs. Enter values such as HunchbackLeather, without spaces or an @ prefix. Names are combined with shopUrls and deduplicated. Do not enter product keywords; this field performs exact shop lookup only.", "items": { "type": "string" }, "default": [] }, "maxShops": { "title": "Maximum shops", "minimum": 1, "maximum": 100, "type": "integer", "description": "Use this to cap the number of shop profiles processed and billed. One successfully stored profile costs $0.015, so 10 shops cap shop-detail events at $0.15. The default is 10 and the hard maximum is 100. This limit does not represent product listings per shop.", "default": 10 }, "includeShopSections": { "title": "Include shop sections", "type": "boolean", "description": "Use this to include public shop-section names when an upstream route exposes them. The default is true; unavailable sections remain null instead of becoming a fabricated empty list. Set false for the leanest profile shape. This does not fetch products inside each section.", "default": true }, "proxyConfiguration": { "title": "Legacy proxy configuration", "type": "object", "description": "Kept for backward compatibility with saved tasks created before version 0.2. The rebuilt actor uses managed provider routes and does not send this configuration to Etsy. Leave the default unchanged. This field does not select the provider or country of returned shop metadata.", "default": { "useApifyProxy": true } } } }, "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 } } } } } } } } } } ```