Pricing

from $2.00 / 1,000 product scrapeds

Etsy Open API v3 - Handmade Products Multi-Country

Query Etsy Open API v3 for active handmade and vintage listings across US/UK/DE/FR/CA/AU/ES/IT. BYOC (bring your own free API keystring from etsy.com/developers). ToS-compliant, anti-bot-immune, 98% margin.

Pricing

from $2.00 / 1,000 product scrapeds

Rating

0.0

(0)

Developer

viralanalyzer

Actor stats

Bookmarked

Total users

Monthly active users

2 days ago

Last modified

🛍️ Etsy Open API v3 — Handmade & Vintage Products (BYOC)

🔗 View on Apify Store | 🇺🇸 English | 🇧🇷 Português

Query Etsy Open API v3 for active handmade and vintage product listings across 8+ countries. BYOC (Bring Your Own Credentials) model — you provide your free personal Etsy API keystring, we handle the rest. Anti-bot-immune (official API), ~98% margin, predictable cost.

✨ Features

Official Etsy Open API v3 — no HTML scraping, no anti-bot blocks
8 country filters — US, UK, DE, FR, CA, AU, ES, IT + ANY
Keyword search with sort by relevance/price/date
Price range filter (minPrice / maxPrice)
Auto-pagination up to 500 results (100 per page hard cap by Etsy)
Rich output — tags, materials, who_made, when_made, num_favorers, views, taxonomy_id, style, shop info
Rate-limit aware — built-in 250ms pause (under 5 QPS personal limit)
NEVER 0 ITEMS guard — actor fails loudly with diagnosis instead of silently succeeding

🔑 BYOC setup (one-time, free, ~5 min)

Sign in at https://www.etsy.com/developers
Click Create a New App (or use an existing one)
After approval (1-7 days for personal review), copy your Keystring from "Your Apps"
Paste the Keystring in the actor input under Etsy API Keystring (BYOC)

Important: New keys arrive with status "Pending Personal Approval". The actor will throw [ETSY_AUTH] 403 API key not found or not active until Etsy reviewers activate it. This is normal — wait for the email.

Limits: Free tier = 5 QPS / 5K queries per day. Plenty for most affiliate research workflows.

📥 Input

Parameter	Type	Required	Default	Description
`keystring`	string (secret)	Yes	—	Your Etsy API keystring (see BYOC setup above)
`searchQuery`	string	Yes	—	Search term (e.g. "handmade jewelry")
`country`	enum	No	`US`	Origin country filter (US/UK/DE/FR/CA/AU/ES/IT/ANY)
`sortOn`	enum	No	`score`	Sort dimension: `score`/`price`/`created`/`updated`
`sortOrder`	enum	No	`desc`	`asc` or `desc`
`minPrice`	integer	No	0	Minimum price (in country currency, 0 = no filter)
`maxPrice`	integer	No	0	Maximum price (0 = no filter)
`maxResults`	integer	No	24	Total listings to fetch (1-500)

Input example

{
  "keystring": "your_etsy_keystring_here",
  "searchQuery": "wedding ring rose gold",
  "country": "US",
  "minPrice": 100,
  "maxPrice": 1000,
  "maxResults": 50
}

📤 Output

Each record contains:

{
  "listingId": 1234567890,
  "title": "Handmade Rose Gold Wedding Ring — Custom Engraving",
  "description": "Beautiful handmade ring crafted in our small studio…",
  "url": "https://www.etsy.com/listing/1234567890/...",
  "price": 245.0,
  "currency": "USD",
  "state": "active",
  "whoMade": "i_did",
  "whenMade": "made_to_order",
  "isSupply": false,
  "isCustomizable": true,
  "isDigital": false,
  "quantity": 999,
  "views": 4521,
  "numFavorers": 138,
  "tags": ["wedding ring", "rose gold", "engagement"],
  "materials": ["14k rose gold", "diamond"],
  "styleTags": ["minimalist"],
  "taxonomyId": 1234,
  "originCountryIso": "US",
  "shop": {
    "shopId": 5555,
    "shopName": "BohoJewelryStudio",
    "url": "https://www.etsy.com/shop/BohoJewelryStudio"
  },
  "thumbnail": "https://i.etsystatic.com/.../il_570xN.jpg",
  "createdAt": 1715000000,
  "updatedAt": 1715800000,
  "countryFilter": "US",
  "source": "etsy-open-api-v3"
}

💰 Pricing

Pay-per-event (PPE): only charged when the actor returns a real listing. Zero results → zero charge. Anti-bot blocks are impossible here (official API).

🚀 Use cases

Affiliate research — surface high-favorers handmade niches before saturation
Price intelligence — track competitor pricing in handmade/vintage verticals
Trend discovery — sort by created desc + score to spot rising listings
Catalog import — seed your own e-commerce or comparison site
SEO content — extract tags + materials for long-tail keyword research

⚠️ Common errors

Error	Cause	Fix
`[ETSY_AUTH] 401 Unauthorized`	Keystring invalid or expired	Verify at https://www.etsy.com/developers/your-apps
`[ETSY_AUTH] 403 API key not found or not active`	Key still Pending Personal Approval	Wait 1-7 days for Etsy review
`[ETSY_RATE] 429 Too Many Requests`	Hit 5 QPS / 5K QPD personal limit	Wait or upgrade Etsy app tier
`[FAIL] Zero listings returned`	Filter too restrictive	Try `country: "ANY"` or broader keyword

🔒 Privacy

Your keystring is passed directly to api.etsy.com over HTTPS. We never store, log, or proxy it through our servers. Mark the input field as secret in Apify Console.

Rakuten Affiliate Merchants — Rakuten API (BYOC)
CJ Affiliate Products — Commission Junction GraphQL (BYOC)
Impact.com Affiliate API — Impact.com REST (BYOC)
Awin Multi-Merchant — Awin Publisher API (BYOC)

🆕 Changelog

v2.0 (2026-05-14): Major refactor from Playwright HTML scraping (HTTP 403 anti-bot blocked all attempts) to Etsy Open API v3 (BYOC). 98% margin, anti-bot-immune, ToS-compliant. Output adds tags, materials, whoMade, views, numFavorers, taxonomyId.
v1.1 (2026-05-14): Playwright + RESIDENTIAL fingerprints attempted; Etsy Akamai still 403 → deprecated.
v1.0 (2026-05-12): Initial CheerioCrawler release.

Português

🛍️ Etsy Open API v3 — Produtos Artesanais e Vintage (BYOC)

Consulta a API oficial Etsy Open API v3 para listings de produtos artesanais e vintage ativos em 8+ países. BYOC (Bring Your Own Credentials) — você fornece sua keystring pessoal grátis do Etsy, nós cuidamos do resto. Imune a anti-bot (API oficial), margem ~98%, custo previsível.

Setup BYOC (uma vez, grátis, ~5 min)

Entre em https://www.etsy.com/developers
Crie um app (ou use um existente)
Após aprovação (1-7 dias para revisão pessoal), copie sua Keystring em "Your Apps"
Cole no campo Etsy API Keystring (BYOC) do input do actor

Importante: novas chaves chegam com status "Pending Personal Approval". O actor retorna [ETSY_AUTH] 403 API key not found or not active até o Etsy ativar. Aguarde o email.

Limites: tier grátis = 5 req/seg / 5K req/dia. Suficiente para a maioria dos casos de uso.

✨ Funcionalidades

API oficial Etsy Open API v3 — sem scraping de HTML, sem bloqueios anti-bot
8 filtros de país — US, UK, DE, FR, CA, AU, ES, IT + ANY
Busca por palavra-chave com ordenação por relevância/preço/data
Filtro de faixa de preço (minPrice / maxPrice)
Paginação automática até 500 resultados (limite de 100 por página imposto pelo Etsy)
Output rico — tags, materials, who_made, when_made, num_favorers, views, taxonomy_id, style, informações da loja
Consciente de rate-limit — pausa interna de 250ms (abaixo do limite pessoal de 5 QPS)
Guard NEVER 0 ITEMS — o actor falha de forma explícita com diagnóstico em vez de ter sucesso silencioso

📥 Entrada

Parâmetro	Tipo	Obrigatório	Padrão	Descrição
`keystring`	string (secreto)	Sim	—	Sua keystring da API do Etsy (veja o setup BYOC acima)
`searchQuery`	string	Sim	—	Termo de busca (ex: "handmade jewelry")
`country`	enum	Não	`US`	Filtro de país de origem (US/UK/DE/FR/CA/AU/ES/IT/ANY)
`sortOn`	enum	Não	`score`	Dimensão de ordenação: `score`/`price`/`created`/`updated`
`sortOrder`	enum	Não	`desc`	`asc` ou `desc`
`minPrice`	integer	Não	0	Preço mínimo (na moeda do país, 0 = sem filtro)
`maxPrice`	integer	Não	0	Preço máximo (0 = sem filtro)
`maxResults`	integer	Não	24	Total de listings a buscar (1-500)

Exemplo de entrada

{
  "keystring": "your_etsy_keystring_here",
  "searchQuery": "wedding ring rose gold",
  "country": "US",
  "minPrice": 100,
  "maxPrice": 1000,
  "maxResults": 50
}

📤 Saída

Cada registro contém:

{
  "listingId": 1234567890,
  "title": "Handmade Rose Gold Wedding Ring — Custom Engraving",
  "description": "Beautiful handmade ring crafted in our small studio…",
  "url": "https://www.etsy.com/listing/1234567890/...",
  "price": 245.0,
  "currency": "USD",
  "state": "active",
  "whoMade": "i_did",
  "whenMade": "made_to_order",
  "isSupply": false,
  "isCustomizable": true,
  "isDigital": false,
  "quantity": 999,
  "views": 4521,
  "numFavorers": 138,
  "tags": ["wedding ring", "rose gold", "engagement"],
  "materials": ["14k rose gold", "diamond"],
  "styleTags": ["minimalist"],
  "taxonomyId": 1234,
  "originCountryIso": "US",
  "shop": {
    "shopId": 5555,
    "shopName": "BohoJewelryStudio",
    "url": "https://www.etsy.com/shop/BohoJewelryStudio"
  },
  "thumbnail": "https://i.etsystatic.com/.../il_570xN.jpg",
  "createdAt": 1715000000,
  "updatedAt": 1715800000,
  "countryFilter": "US",
  "source": "etsy-open-api-v3"
}

🚀 Casos de Uso

Pesquisa de afiliação — identificar nichos artesanais com muitos favoritos antes da saturação
Inteligência de preços — acompanhar preços de concorrentes nos verticais artesanal/vintage
Descoberta de tendências — ordenar por created desc + score para detectar listings em ascensão
Importação de catálogo — popular seu próprio e-commerce ou site de comparação
Conteúdo de SEO — extrair tags + materials para pesquisa de palavras-chave de cauda longa

⚠️ Erros Comuns

Erro	Causa	Correção
`[ETSY_AUTH] 401 Unauthorized`	Keystring inválida ou expirada	Verifique em https://www.etsy.com/developers/your-apps
`[ETSY_AUTH] 403 API key not found or not active`	Chave ainda em Pending Personal Approval	Aguarde 1-7 dias pela revisão do Etsy
`[ETSY_RATE] 429 Too Many Requests`	Atingiu o limite pessoal de 5 QPS / 5K QPD	Aguarde ou faça upgrade do tier do app no Etsy
`[FAIL] Zero listings returned`	Filtro restritivo demais	Tente `country: "ANY"` ou palavra-chave mais ampla

💰 Preços

Pay-per-event (PPE): você só é cobrado quando o actor retorna um listing real. Zero resultados → zero cobrança. Bloqueios anti-bot são impossíveis aqui (API oficial).

🔒 Privacidade

Sua keystring é enviada diretamente para api.etsy.com via HTTPS. Nós nunca armazenamos, registramos em log ou intermediamos por nossos servidores. Marque o campo de entrada como secreto no Apify Console.

📚 Actors Relacionados

Rakuten Affiliate Merchants — API Rakuten (BYOC)
CJ Affiliate Products — Commission Junction GraphQL (BYOC)
Impact.com Affiliate API — Impact.com REST (BYOC)
Awin Multi-Merchant — Awin Publisher API (BYOC)

🆕 Histórico de Versões

v2.0 (2026-05-14): Refatoração major de scraping HTML com Playwright (HTTP 403 anti-bot bloqueou todas as tentativas) para Etsy Open API v3 (BYOC). Margem de 98%, imune a anti-bot, em conformidade com os ToS. A saída adiciona tags, materials, whoMade, views, numFavorers, taxonomyId.
v1.1 (2026-05-14): Playwright + fingerprints RESIDENTIAL tentados; Akamai do Etsy ainda retornou 403 → descontinuado.
v1.0 (2026-05-12): Release inicial com CheerioCrawler.

Etsy Scraper - Handmade & Vintage Products

thirdwatch/etsy-scraper

Scrape Etsy search results. Returns name, shop, price, rating, image, and URL.

Thirdwatch

Etsy Scraper — Listings, Prices & Tags via Official API

bovi/etsy-listings

Scrape Etsy active listings: title, price, currency, quantity, tags, views, favorites, and taxonomy. Uses the official Etsy Open API v3 — structured, reliable data. Free Etsy API key required (etsy.com/developers — takes 5 min). Pay per result.