# Etsy API Scraper (`rl1987/etsy-api-scraper`) Actor

Scrapes Etsy category tree, search results, listing details, and reviews via the Etsy Android app's private signed API.

- **URL**: https://apify.com/rl1987/etsy-api-scraper.md
- **Developed by:** [R.L.](https://apify.com/rl1987) (community)
- **Categories:** E-commerce
- **Stats:** 2 total users, 1 monthly users, 70.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $0.50 / 1,000 search result (plp) rows

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 web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
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.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — 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

### What does Etsy Scraper do?

Etsy Scraper pulls product data straight from [Etsy](https://www.etsy.com) in seconds: **category tree**, **search results**, **product details**, and **customer reviews**. Give it a search term or a category, hit Run, and get clean, structured data back — no manual copy-pasting, no browser extensions, no CAPTCHAs to fight through.

Built on the Apify platform, so every run comes with scheduling, API access, one-click export to JSON/CSV/Excel, and integrations with Google Sheets, Make, Zapier, and dozens of other tools.

### Why use Etsy Scraper?

- **Market research** — see what's selling, how it's priced, and what shoppers say about it, across an entire category.
- **Competitor tracking** — watch specific shops or listings over time with a scheduled run; catch price changes, new listings, and review trends as they happen.
- **Product sourcing** — find listings and shops matching a niche before you commit to sourcing or dropshipping it.
- **Review & sentiment analysis** — pull every review for a product to feed into your own analysis, without reading them one by one.

### How to use Etsy Scraper

1. Click **Try for free** (or **Run** if you already have it).
2. Pick a **mode**: search by keyword, browse a category, or look up specific listings by ID.
3. Set how many results you want, and optionally filter by price or sort order.
4. Click **Start**.
5. When the run finishes, open the **Output** tab to view, filter, and export your data.

### Input

| Field | What it does |
|---|---|
| Mode | What to fetch: a full search-and-detail crawl, search results only, category tree only, or specific listings by ID. |
| Search keywords | Free-text search, e.g. "ceramic mug". |
| Category | Narrow results to a category, or browse the category tree from here. |
| Listing IDs | Fetch specific products directly by their Etsy listing ID. |
| Result limits | Cap how many search results, product detail pages, and reviews per product to fetch. |
| Sort & filters | Sort by best match, newest, price, or reviews; optional min/max price and ship-to country. |

Full field descriptions are in the Input tab.

### Output

Every result — search result, product, or review — is a row in the dataset, ready to view in the Output tab or download as JSON, CSV, Excel, HTML, or XML.

```json
{
  "recordType": "listing",
  "listingId": 123456789,
  "title": "Handmade Ceramic Mug",
  "price": "24.99",
  "currencyCode": "USD",
  "shopId": 987654,
  "shopName": "ExampleShop",
  "reviewsSummary": { "count": 312 }
}
```

#### Data table

| Field | Description |
|---|---|
| `recordType` | `category`, `searchResult`, `listing`, or `review`. |
| `title` | Product or category title. |
| `price` / `currencyCode` | Listing price. |
| `shopName` / `shopId` | The seller's shop. |
| `rating` / `reviewText` | Review score and text (review rows). |
| `url` | Link to the listing on Etsy. |

Every row also carries the full raw data Etsy returned for it, so nothing is ever left out even if it's not one of the fields above.

### Pricing

Pay only for what you get:

| You get | Price |
|---|---|
| Search results | $0.50 per 1,000 rows |
| Product details | $0.50 per 1,000 rows |
| Reviews | $0.50 per 1,000 rows |
| Category tree | Free |

A category-tree-only run costs nothing but Apify platform usage. There's no separate subscription or per-call fee beyond the table above.

### Tips for getting the most out of it

- Start small (a few dozen results) to check the data shape before scaling up to a full run.
- Use the result limits to control cost: fetching product details and reviews for every search result adds up fast on a broad search — narrow your keywords or cap "product details to fetch" instead.
- Schedule recurring runs (daily/weekly) to track price and review changes on the same products over time.

### FAQ

**Is this legal?** Etsy Scraper only reads publicly visible product and review information, the same data any shopper sees when browsing Etsy. You're responsible for how you use the data — check Etsy's terms of service and applicable laws for your use case.

**Why did a run return fewer results than I asked for?** Some very narrow searches or categories simply don't have that many results on Etsy. Try broader keywords or a parent category.

**Something's not working / found a bug?** Open an issue on the Actor's Issues tab — we're happy to help, and custom extensions/integrations are available on request.

# Actor input Schema

## `mode` (type: `string`):

What to scrape.

## `keywords` (type: `string`):

Free-text search query. Used in FULL and SEARCH modes.

## `taxonomyId` (type: `integer`):

Restrict search to this category, or root the category tree crawl here (TAXONOMY mode). Leave empty to crawl the full tree / search without a category filter.

## `listingIds` (type: `array`):

Listing IDs to fetch directly, one per line. Used in LISTING\_DETAILS mode.

## `maxSearchResults` (type: `integer`):

Max number of PLP results to collect (SEARCH and FULL modes).

## `maxListingDetails` (type: `integer`):

In FULL mode, how many of the search results get a follow-up PDP + reviews fetch (the rest stay as search-result cards only).

## `maxReviewsPerListing` (type: `integer`):

Cap on reviews fetched per listing (FULL and LISTING\_DETAILS modes). 0 disables review fetching.

## `sortOn` (type: `string`):

Search result ordering field.

## `sortOrder` (type: `string`):

Direction for sortOn.

## `minPrice` (type: `integer`):

Optional minimum price filter for search.

## `maxPrice` (type: `integer`):

Optional maximum price filter for search.

## `shipTo` (type: `string`):

ISO country code used for shipping-aware search results.

## `proxyConfiguration` (type: `object`):

Recommended: Etsy rate-limits by IP even with a valid signature.

## Actor input object example

```json
{
  "mode": "FULL",
  "keywords": "ceramic mug",
  "listingIds": [],
  "maxSearchResults": 50,
  "maxListingDetails": 20,
  "maxReviewsPerListing": 20,
  "sortOn": "score",
  "sortOrder": "down",
  "shipTo": "US",
  "proxyConfiguration": {
    "useApifyProxy": true
  }
}
```

# Actor output Schema

## `dataset` (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 '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "keywords": "ceramic mug"
};

// Run the Actor and wait for it to finish
const run = await client.actor("rl1987/etsy-api-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 '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = { "keywords": "ceramic mug" }

# Run the Actor and wait for it to finish
run = client.actor("rl1987/etsy-api-scraper").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "keywords": "ceramic mug"
}' |
apify call rl1987/etsy-api-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,rl1987/etsy-api-scraper"
        }
    }
}

```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/c0GvZNcrq5WNcvFkY/builds/tOXxe4RGyuyoCwfM1/openapi.json