{ "openapi": "3.0.1", "info": { "title": "Etsy Scraper: Listings, Prices, Ads, Reviews", "description": "Scrape Etsy phrases, categories, shops, listing links or ids in 29 Etsy markets, no login. Get price, original price, discount, free shipping, shop rating, ad slot and organic rank, plus optional listing pages, reviews and shops. JSON, CSV or Excel via API or schedule; pay per listing.", "version": "0.1", "x-build-id": "GZhDMfcIpoMkjIg8d" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/automation_craft~etsy-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-automation_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/automation_craft~etsy-scraper/runs": { "post": { "operationId": "runs-sync-automation_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/automation_craft~etsy-scraper/run-sync": { "post": { "operationId": "run-sync-automation_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": { "searchTerms": { "title": "Search phrases", "type": "array", "description": "Words to search, one phrase per line, as a buyer types them (\"leather wallet\", \"personalized necklace\"). Each phrase is read on Etsy's own page for it (etsy.com/market/): 40 results a page, up to 25 pages (1,000 results), plus the ad slots of each page. Etsy fills every phrase page, so a phrase nobody sells returns loosely related listings; turn on onlyTitleMatches to keep only listings whose title holds every word. A phrase with a slash is refused (write 1 12 for 1/12).", "items": { "type": "string" } }, "startUrls": { "title": "Etsy links", "type": "array", "description": "Etsy links: a phrase page (https://www.etsy.com/market/leather_wallet), a category page (https://www.etsy.com/c/jewelry/necklaces), a listing (https://www.etsy.com/listing/1879178124/...) or a shop (https://www.etsy.com/shop/ShopName). A link of a regional Etsy site (/uk/, /de/ ...) must match the country setting. Etsy's site search links (/search?q=) are not read; put their words in Search phrases. Links that carry filters (price, sort) are refused: set those filters below.", "items": { "type": "string" } }, "listingIds": { "title": "Listing links or ids", "type": "array", "description": "Etsy listing ids (1879178124) or listing links. They are read 100 at a time through Etsy's own card call; a listing Etsy no longer shows gets a free listing_not_found row. Turn on includeDetails to read each listing's page as well.", "items": { "type": "string" } }, "shopNames": { "title": "Shops", "type": "array", "description": "Shop names (CaitlynMinimalist) or shop links. Each shop gives its latest 10 listings from its RSS feed (Listing events). Turn on includeShopPages for every listing of the shop and its profile.", "items": { "type": "string" } }, "shopIds": { "title": "Shop ids", "type": "array", "description": "Etsy shop ids (numbers such as 35055979). The run reads each shop's name from Etsy first (from the shop's reviews; a shop without reviews cannot be named this way and gets a free row), then reads the shop like a shop name.", "items": { "type": "string" } }, "country": { "title": "Country (Etsy market)", "type": "string", "description": "Two letter country code of the Etsy market to read, for example US, GB, DE, CA or AU. Etsy shows prices in the market's currency, with VAT where it applies, and its own selection of listings for that country. Default: US." }, "currency": { "title": "Display currency", "type": "string", "description": "One of Etsy's 30 display currencies (USD, EUR, GBP, CAD, AUD, JPY ...). Prices are converted by Etsy itself, as a shopper sees them after picking a currency. Leave it empty for the market's own currency." }, "language": { "title": "Title language", "type": "string", "description": "One of Etsy's interface languages (de, fr, es, it, ja, nl, pl, pt, ru, sv, en-GB ...). Titles come in Etsy's own translation for that language, and the English title stays in titleEnglish; the title filters look in both titles. Leave it empty for English." }, "maxItems": { "title": "Maximum listings", "minimum": 1, "maximum": 100000, "type": "integer", "description": "The most listing rows this run delivers, over every target together. Reviews and the shop profile rows do not count toward it. Default: 100." }, "maxItemsPerSearch": { "title": "Maximum listings per phrase or category", "minimum": 1, "maximum": 100000, "type": "integer", "description": "The most listing rows one phrase or category delivers. Leave empty for no per phrase limit." }, "maxPagesPerSearch": { "title": "Pages per phrase or category", "minimum": 1, "maximum": 250, "type": "integer", "description": "How many result pages to read per phrase, category or shop. A phrase page holds 40 results plus ad slots and Etsy stops at page 25; a category page holds about 64. Leave empty for every page." }, "startPage": { "title": "Start page", "minimum": 1, "maximum": 250, "type": "integer", "description": "The result page each phrase or category starts on (1 = the first page). A link's own page number wins for that link." }, "maxItemsPerShop": { "title": "Maximum listings per shop", "minimum": 1, "maximum": 100000, "type": "integer", "description": "The most listing rows one shop delivers. Leave empty for every listing of the shop (up to Maximum listings)." }, "includeAds": { "title": "Include ad slots", "type": "boolean", "description": "Deliver the listings Etsy shows in paid ad slots (isAd: true, with their adSlot). Off: only organic results. A listing shown both as an ad and organically is one row with both positions.", "default": true }, "minPrice": { "title": "Minimum price", "minimum": 0, "type": "number", "description": "Only listings at or above this price, in the run's currency." }, "maxPrice": { "title": "Maximum price", "minimum": 0, "type": "number", "description": "Only listings at or below this price, in the run's currency." }, "onSaleOnly": { "title": "On sale only", "type": "boolean", "description": "Only listings with a sale price below their original price.", "default": false }, "freeShippingOnly": { "title": "Free shipping only", "type": "boolean", "description": "Only listings whose card shows free shipping or free delivery.", "default": false }, "minRating": { "title": "Minimum shop rating", "minimum": 0, "maximum": 5, "type": "number", "description": "Only listings whose shop is rated at least this (0 to 5, two decimals as Etsy keeps them): the stars an Etsy search card shows are the shop's. Listings without a rating are left out when this is set." }, "minReviews": { "title": "Minimum shop reviews", "minimum": 0, "type": "integer", "description": "Only listings whose shop has at least this many reviews (the count an Etsy card shows is the shop's; Etsy rounds it above 1,000, 9.1k, and the row says so in shopReviewCountRounded)." }, "digitalOnly": { "title": "Digital downloads only", "type": "boolean", "description": "Only listings marked Digital Download on their card (with includeDetails, also on the listing page).", "default": false }, "physicalOnly": { "title": "Physical items only", "type": "boolean", "description": "Leave out listings marked Digital Download.", "default": false }, "titleIncludes": { "title": "Title must contain", "type": "array", "description": "Words that must all appear in the listing title (case does not matter).", "items": { "type": "string" } }, "titleExcludes": { "title": "Title must not contain", "type": "array", "description": "Words that leave a listing out when its title holds any of them.", "items": { "type": "string" } }, "onlyTitleMatches": { "title": "Only titles holding every search word", "type": "boolean", "description": "Keep only listings whose title holds every word of the phrase (by word start: mug matches mugs). Every row carries titleMatchesSearch either way.", "default": false }, "includeDetails": { "title": "Listing details (listing page)", "type": "boolean", "description": "Read each delivered listing's own page: description, all images and the video, variations with their prices and sold out options, stock, materials, item attributes, who made it, ships from, delivery estimate, cost to ship, returns, favourites, listed date, the in carts, bought or viewed in the last 24 hours line Etsy shows, review tags, sample reviews, shop name, sales, years on Etsy and location. Charged as Listing details per listing page read; a page that cannot be read is free and the row comes without details.", "default": false }, "includeDescription": { "title": "Keep the description", "type": "boolean", "description": "With listing details: keep the full description text in each row. Off: leave it out (shorter rows).", "default": true }, "includeImages": { "title": "Keep every image", "type": "boolean", "description": "With listing details: keep the list of every image link in each row. Off: only the main image.", "default": true }, "handmadeOnly": { "title": "Handmade only", "type": "boolean", "description": "Only listings that Etsy marks as made by the shop itself (the item details say Made by and the shop's name). Needs includeDetails (the listing page says it).", "default": false }, "vintageOnly": { "title": "Vintage only", "type": "boolean", "description": "Only vintage listings: Etsy marks them Handpicked by and the shop's name in the item details. Needs includeDetails (the listing page says it).", "default": false }, "starSellerOnly": { "title": "Star Sellers only", "type": "boolean", "description": "Only listings of shops that hold the Star Seller badge. Needs includeDetails (the listing page says it).", "default": false }, "bestsellerOnly": { "title": "Bestsellers only", "type": "boolean", "description": "Only listings Etsy marks Bestseller. Needs includeDetails (the listing page says it).", "default": false }, "etsysPickOnly": { "title": "Etsy's Picks only", "type": "boolean", "description": "Only listings Etsy marks Etsy's Pick. Needs includeDetails (the listing page says it).", "default": false }, "personalizableOnly": { "title": "Personalizable only", "type": "boolean", "description": "Only listings that take a personalization. Needs includeDetails (the listing page says it).", "default": false }, "shipsFromCountries": { "title": "Ships from (countries)", "type": "array", "description": "Only listings that ship from one of these two letter country codes (US, GB, DE ...). Needs includeDetails.", "items": { "type": "string" } }, "minFavorites": { "title": "Minimum favourites", "minimum": 0, "type": "integer", "description": "Only listings with at least this many favourites. Needs includeDetails." }, "listedAfter": { "title": "Listed on or after", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "type": "string", "description": "Only listings whose Listed on date (Etsy's listed or renewed date) is on or after this day, YYYY-MM-DD. Needs includeDetails." }, "listedBefore": { "title": "Listed on or before", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "type": "string", "description": "Only listings whose Listed on date is on or before this day, YYYY-MM-DD. Needs includeDetails." }, "categoryContains": { "title": "Category contains", "type": "string", "description": "Only listings whose Etsy category path holds this text (for example Wallets). Needs includeDetails." }, "madeByKinds": { "title": "Made by (kinds)", "type": "array", "description": "Only listings whose page names the shop with one of these words (Etsy's own wording in the item details). Needs includeDetails.", "items": { "type": "string", "enum": [ "made by", "designed by", "handpicked by", "sourced by" ], "enumTitles": [ "Made by the shop", "Designed by the shop", "Handpicked by the shop (vintage)", "Sourced by the shop" ] } }, "includeReviews": { "title": "Reviews", "type": "boolean", "description": "Deliver buyer reviews of every delivered listing (8 a call from Etsy's own review call): rating, date, text, translation, photo, the buyer's display name, the listing and the seller's reply. Charged per review; a listing without reviews costs nothing.", "default": false }, "maxReviewsPerListing": { "title": "Reviews per listing", "minimum": 1, "maximum": 2400, "type": "integer", "description": "The most reviews delivered per listing. Default: 8 (one call)." }, "reviewsSort": { "title": "Review order", "enum": [ "relevance", "newest", "highest", "lowest" ], "type": "string", "description": "The order Etsy returns reviews in: Etsy's own four orders.", "default": "relevance" }, "reviewsRatings": { "title": "Review star ratings", "type": "array", "description": "With reviews: only reviews of these star ratings (Etsy's own filter, one rating at a time, read in the order given under one cap). Leave empty for every rating.", "items": { "type": "string", "enum": [ "5", "4", "3", "2", "1" ], "enumTitles": [ "5 stars", "4 stars", "3 stars", "2 stars", "1 star" ] } }, "reviewsTopic": { "title": "Reviews about this topic only", "type": "string", "description": "Only reviews Etsy files under this topic (Etsy's own topics: Quality, Appearance, Shipping & Packaging, Customer service, Price ...; a listing's topics come in its first review call)." }, "reviewsWithPhotosOnly": { "title": "Reviews with a photo only", "type": "boolean", "description": "Only reviews that carry the buyer's photo (left out here, free: Etsy's review call has no photo filter).", "default": false }, "shopReviews": { "title": "Whole shop reviews", "type": "boolean", "description": "With includeReviews and a shop you named: deliver the shop's own reviews across all its listings as well.", "default": false }, "maxReviewsPerShop": { "title": "Reviews per shop", "minimum": 1, "maximum": 2400, "type": "integer", "description": "The most shop reviews delivered per shop. Default: 100." }, "includeShopPages": { "title": "Every listing of a shop (shop pages)", "type": "boolean", "description": "Read each shop's own pages through Apify's own unblocker: every listing of the shop in the shop's order (about 40 a page) and its profile row. Each page read is a Shop page event; an attempt the unblocker could not answer is free. The unblocker is slow (30 to 60 seconds a page) and at busy hours often has no free browser: after six failures in a row the run stops asking it, and each shop's latest 10 listings from its RSS feed stand.", "default": false }, "includeShopProfile": { "title": "Shop profile rows", "type": "boolean", "description": "With includeShopPages: for each shop you named, one free row with its id, name, headline, location, Star Seller, rating, review count, total sales, admirers, year it opened, latest activity, active listing count, sections, announcement and FAQ.", "default": true }, "shopSearchQuery": { "title": "Search inside the shop", "type": "string", "description": "With shop pages: the words for the shop's own search box (search_query on its shop pages); only the shop's listings that match are read, and the shop's latest listings from its RSS feed are not delivered. Each shop page read is a Shop page event." }, "shopSortOrder": { "title": "Shop listing order", "enum": [ "featured", "newest", "priceAsc", "priceDesc" ], "type": "string", "description": "With shop pages: the shop's own order of its listings. featured is the order the shop page opens with; newest, priceAsc and priceDesc are the shop's own sort orders. Any order other than featured leaves out the RSS feed's latest listings.", "default": "featured" }, "shopSectionId": { "title": "Shop section", "type": "string", "description": "With shop pages: one section of the shop, by its id (the shop row lists each section with its id; a section link carries it as section_id). Only that section's listings are read, newest first unless a shop listing order is set; the RSS feed's latest listings are not delivered." }, "includeShopNames": { "title": "Shop names on search rows", "type": "boolean", "description": "Search and category cards carry the shop id but not its name. On: one extra Etsy call per new shop names it (free, about one second per shop). Listing details always carry the shop name.", "default": false }, "includeRelatedSearches": { "title": "Related searches", "type": "boolean", "description": "Add Etsy's related searches and its own autosuggest phrases for each phrase to that phrase's free search row (relatedSearches, autocomplete).", "default": true }, "sortResultsBy": { "title": "Order of the delivered rows", "enum": [ "etsy", "priceAsc", "priceDesc", "ratingDesc", "reviewCountDesc", "discountDesc", "favoritesDesc", "newestListedFirst", "inCartsDesc", "viewsLast24hDesc", "shopSalesDesc" ], "type": "string", "description": "Etsy's own order delivers each page as it is read. Any other order collects each phrase's or category's rows and delivers them sorted when its walk ends, so it allows at most 2,000 listings in a run with listing details and 20,000 without.", "default": "etsy" }, "dedupeAcrossSearches": { "title": "Each listing once per run", "type": "boolean", "description": "On (the default): a listing that several of your searches, categories or shops find is delivered and charged once per run. Off: it is delivered once for every target that finds it (each with that target's rank, page and position), and each such row is a Listing, for rank tracking across searches.", "default": true }, "includeRawData": { "title": "Raw page data", "type": "boolean", "description": "With listing details: add a raw object with the listing page's own structured values.", "default": false }, "customMapFunction": { "title": "Custom output function", "type": "string", "description": "A JavaScript function (row) => value, run on each listing row in a sandbox with a time limit of a quarter second a row (a row that meets it is tried once more; a function that runs past it on 3 rows is not run again); what it returns is added to the row as custom. It never replaces the row's own fields." }, "includePersonalData": { "title": "Include personal data", "type": "boolean", "description": "Adds the names of private persons that Etsy shows publicly: the shop owner's name on a listing (shopOwnerName), the shop members of a shop profile (members), a review buyer's profile link (buyerProfileUrl) and the name of the person who replied to a review (sellerResponderName). Off: those fields are null. You are responsible for a lawful use of personal data, GDPR included.", "default": false }, "maxConcurrency": { "title": "Phrases read at once", "minimum": 1, "maximum": 4, "type": "integer", "description": "How many phrases or categories are walked at the same time. Default: 2." }, "maxRuntimeSeconds": { "title": "Maximum run time (seconds)", "minimum": 30, "maximum": 86400, "type": "integer", "description": "Stop starting new work after this many seconds; rows in hand are delivered and every target not reached gets a free skipped row." }, "proxyConfiguration": { "title": "Your own proxies", "type": "object", "description": "Optional. Your own proxy addresses (proxyUrls) replace the residential exits this Actor uses for listing, category and phrase pages. Apify proxy groups chosen here are not used: the Actor picks its own egress per page kind." } } }, "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 } } } } } } } } } }