{ "openapi": "3.0.1", "info": { "title": "Etsy Scraper โ€” Listings, Shops, Reviews & Keyword Research", "description": "Etsy research tools charge monthly and still hide the raw data. Get it yourself: listings, shops, reviews, prices, sales estimates, keyword research and ad ranks, exported to JSON, CSV or Excel. Pay per result, no subscription, no login.", "version": "1.0", "x-build-id": "oS06mkQayuCdFr31l" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/crawl_craft~etsy-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-crawl_craft-etsy-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/crawl_craft~etsy-scraper/runs": { "post": { "operationId": "runs-sync-crawl_craft-etsy-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/crawl_craft~etsy-scraper/run-sync": { "post": { "operationId": "run-sync-crawl_craft-etsy-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": { "urls": { "title": "๐Ÿ”— Etsy links (bulk)", "type": "array", "description": "One Etsy link per line, as many as you like. Supported: search pages (https://www.etsy.com/search?q=necklace&min=20 โ€” the link's filters and page number are used), category and market pages (https://www.etsy.com/c/jewelry/necklaces, https://www.etsy.com/market/boho_rug โ€” searched by their keyword), listing pages (https://www.etsy.com/listing/1721240021) and shop pages (https://www.etsy.com/shop/YourNamesJewelry, a section_id in the link is kept). Local versions such as etsy.com/uk/... work too.", "items": { "type": "string" } }, "queries": { "title": "๐Ÿ” Search keywords", "type": "array", "description": "Keywords typed like a shopper would, e.g. \"boho wall art\". Each keyword is a separate search with its own ranks and its own keyword report. A link pasted here is handled as a link.", "items": { "type": "string" } }, "listingIds": { "title": "๐Ÿ†” Listing IDs", "type": "array", "description": "Etsy listing IDs (e.g. 1721240021) or listing links. Returns the card data of each listing โ€” handy for price and availability tracking. A listing Etsy no longer shows comes back with isAvailable = false.", "items": { "type": "string" } }, "shops": { "title": "๐Ÿช Shop names", "type": "array", "description": "Shop names (e.g. YourNamesJewelry) or shop links. Each shop gets a shop report (rating, sales, sections, sales estimate), its listings and its reviews.", "items": { "type": "string" } }, "maxPages": { "title": "๐Ÿ“„ Max pages per search", "minimum": 1, "maximum": 500, "type": "integer", "description": "How many result pages to read for each search (about 48 listings plus ads per page). The number of pages available depends on the sort order. Free plan users are limited to 10 items per run; paid plans have no limit.", "default": 1 }, "maxResults": { "title": "๐Ÿ“Š Max listings per search", "minimum": 0, "type": "integer", "description": "Stop each search after this many listings (after your filters). 0 = everything the pages above return. Free plan users are limited to 10 items per run; paid plans have no limit.", "default": 0 }, "sort": { "title": "๐Ÿ”ƒ Sort order", "enum": [ "relevance", "newest", "price-asc", "price-desc", "reviews", "carts", "views" ], "type": "string", "description": "Order of search results. \"Most in carts\" and \"Most viewed\" re-rank each search by live demand and switch on demand signals automatically (slower).", "default": "relevance" }, "country": { "title": "๐ŸŒ Ship-to country", "enum": [ "US", "GB", "CA", "AU", "NZ", "DE", "FR", "IT", "ES", "NL", "IE", "BE", "AT", "PT", "FI", "GR", "JP", "BR", "MX", "CH", "SE", "NO", "DK", "PL", "IN", "SG", "HK", "IL", "ZA", "MY", "PH", "TR", "VN", "ID", "MA" ], "type": "string", "description": "Country used for search results, prices and shipping quotes. Prices are shown in this country's currency unless you pick a currency below.", "default": "US" }, "currency": { "title": "๐Ÿ’ฑ Currency (optional)", "enum": [ "USD", "EUR", "GBP", "CAD", "AUD", "NZD", "JPY", "BRL", "MXN", "CHF", "SEK", "NOK", "DKK", "PLN", "INR", "SGD", "HKD", "ILS", "ZAR", "MYR", "PHP", "TRY", "VND", "IDR", "MAD" ], "type": "string", "description": "Show prices in another currency, e.g. EUR. Leave empty to use the ship-to country's currency. If Etsy does not support the currency, prices come back in USD and currencyCode says USD." }, "minPrice": { "title": "๐Ÿ’ต Min price", "minimum": 0, "type": "number", "description": "Lowest price to keep, in the run currency (the sale price counts when a listing is on sale).", "default": 0 }, "maxPrice": { "title": "๐Ÿ’ฐ Max price", "minimum": 0, "type": "number", "description": "Highest price to keep, in the run currency. If min is above max, the two are swapped." }, "onSaleOnly": { "title": "๐Ÿ”ฅ On sale only", "type": "boolean", "description": "Keep only discounted listings.", "default": false }, "freeShippingOnly": { "title": "๐Ÿšš Free shipping only", "type": "boolean", "description": "Keep only listings that show free shipping.", "default": false }, "digitalOnly": { "title": "๐Ÿ’พ Digital downloads only", "type": "boolean", "description": "Keep only digital download listings.", "default": false }, "handmadeOnly": { "title": "๐Ÿงถ Handmade only", "type": "boolean", "description": "Drops listings marked as Designed by, Handpicked by or Sourced by a seller. Listings that show no maker line are kept.", "default": false }, "starSellerOnly": { "title": "๐ŸŒŸ Star Sellers only", "type": "boolean", "description": "Keep only listings from Star Seller shops.", "default": false }, "etsyPicksOnly": { "title": "๐Ÿ’Ž Etsy's Picks only", "type": "boolean", "description": "Keep only listings picked by Etsy's editors.", "default": false }, "shopLocation": { "title": "๐Ÿ“ Shop location ID", "type": "string", "description": "Only shops located in a region, as an Etsy location ID (the locationQuery value in an Etsy search link, e.g. 2635167 = United Kingdom)." }, "minShopRating": { "title": "โญ Min shop rating", "minimum": 0, "maximum": 5, "type": "number", "description": "Keep only listings whose shop rating is at least this value, e.g. 4.8." }, "minShopReviews": { "title": "๐Ÿ’ฌ Min shop reviews", "minimum": 0, "type": "integer", "description": "Keep only listings whose shop has at least this many reviews, e.g. 1000." }, "titleIncludes": { "title": "โœ… Title must include", "type": "array", "description": "Keep a listing only when its title contains at least one of these words (not case-sensitive).", "items": { "type": "string" } }, "titleExcludes": { "title": "๐Ÿšซ Title must not include", "type": "array", "description": "Drop every listing whose title contains one of these words (not case-sensitive), e.g. digital, download.", "items": { "type": "string" } }, "includeAds": { "title": "๐Ÿ“ข Include sponsored listings", "type": "boolean", "description": "Keep sponsored (ad) listings. They are marked with runningAds = true and their own adRank; organic listings get organicRank.", "default": true }, "dedupeAcrossQueries": { "title": "๐Ÿงน Remove duplicates across searches", "type": "boolean", "description": "Save each listing once even if several searches find it. Turn off to keep a row per search โ€” useful for tracking the rank of one listing for several keywords.", "default": true }, "maxScanned": { "title": "๐Ÿ”ฌ Max listings checked per search", "minimum": 0, "type": "integer", "description": "When strict filters drop most rows, stop a search after checking this many listings. 0 = no cap.", "default": 3000 }, "includeSellerDetails": { "title": "๐Ÿ‘ค Seller details for every row", "type": "boolean", "description": "Fill shop owner, years on Etsy, total sales, location and custom orders on every listing (slower).", "default": true }, "includeDemandSignals": { "title": "๐Ÿ“ˆ Live demand signals", "type": "boolean", "description": "Adds views in the last 24 hours, number of carts, stock left, bought in the last 24 hours, high sales volume, sale end text, all photos and photo count (slower).", "default": false }, "includeShipping": { "title": "๐Ÿ“ฆ Shipping & returns", "type": "boolean", "description": "Adds shipping cost to the ship-to country, ships from, delivery estimate, returns and exchanges accepted, and return window (slower).", "default": false }, "shipToPostalCode": { "title": "๐Ÿ“ฎ Ship-to postal code", "type": "string", "description": "Postal code for shipping quotes in countries with calculated shipping. Leave empty to use a capital-city code for US, GB, CA, AU and IN." }, "maxListingsPerShop": { "title": "๐Ÿ›’ Max listings per shop", "minimum": 0, "type": "integer", "description": "How many listings to collect from each shop. 0 = all. Free plan users are limited to 10 items per run; paid plans have no limit.", "default": 10 }, "shopSort": { "title": "๐Ÿ“š Shop listing order", "enum": [ "date_desc", "custom", "relevance", "price_asc", "price_desc" ], "type": "string", "description": "Order of each shop's listings.", "default": "date_desc" }, "includeReviews": { "title": "๐Ÿ“ Shop reviews", "type": "boolean", "description": "Save the shop's reviews as rows and add a monthly sales estimate to the shop report.", "default": true }, "maxReviewsPerShop": { "title": "๐Ÿงพ Max reviews per shop", "minimum": 0, "type": "integer", "description": "How many of the newest reviews to collect per shop. 0 = all. Free plan users are limited to 10 items per run; paid plans have no limit.", "default": 10 }, "reviewRate": { "title": "๐Ÿ“ Sales estimate tuning", "minimum": 0.01, "maximum": 1, "type": "number", "description": "Tuning value for the sales estimate. Leave the default if you are unsure.", "default": 0.12 }, "keywordResearch": { "title": "๐Ÿง  Keyword research report", "type": "boolean", "description": "One report per search: total results, competition level, price bands, share of bestsellers / sale / free shipping / Star Sellers, top shops, related keywords and the most used title words.", "default": true }, "monitor": { "title": "๐Ÿ“ก Track changes between runs", "type": "boolean", "description": "Compare every listing with the previous run: isNew marks new listings and changes lists what moved (price, rank, views, carts, stock, bestseller, availability, shipping). Shop reports get reviews and estimated sales since the last run.", "default": false }, "monitorKey": { "title": "๐Ÿ”– Monitor name", "type": "string", "description": "Name of the saved history. Use a different name for each thing you track, e.g. necklace-us.", "default": "default" }, "monitorOnlyChanges": { "title": "๐Ÿ†• Only new or changed listings", "type": "boolean", "description": "With change tracking on, save only listings that are new or changed since the last run (the first run saves everything).", "default": false }, "concurrency": { "title": "๐Ÿš€ Parallel requests", "minimum": 1, "maximum": 20, "type": "integer", "description": "How many pages or listings are loaded at the same time. Lower it if runs are unstable.", "default": 5 }, "maxRetries": { "title": "๐Ÿ” Retries per request", "minimum": 1, "maximum": 10, "type": "integer", "description": "Total tries per request when it fails.", "default": 3 }, "proxyConfiguration": { "title": "๐ŸŒ Proxy", "type": "object", "description": "Optional. Choose the proxy settings for your run. Leave the default if you are unsure.", "default": { "useApifyProxy": 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 }, "PROXY_UNBLOCKER_UNITS": { "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 }, "PROXY_UNBLOCKER_UNITS": { "type": "integer", "example": 0 } } } } } } } } } }