# Etsy Scraper Goat (`goat255/etsy-scraper`) Actor

Scrape Etsy listings, shops, and search results without a login. Pull a shop's full catalog, search results for any keyword, or a single listing in full detail with price, rating, reviews, and image gallery. Walks pagination up to your chosen limit.

- **URL**: https://apify.com/goat255/etsy-scraper.md
- **Developed by:** [Goutam Soni](https://apify.com/goat255) (community)
- **Categories:** Automation, Lead generation, Business
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

$5.10 / 1,000 listing scrapeds

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

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

## Etsy Scraper

Extract Etsy marketplace data at scale without a login or API key. Pull a shop's full catalog, search results for any keyword, or a single listing in full detail with price, rating, reviews, and the complete image gallery. The scraper walks pagination automatically up to the limit you set, so you can collect hundreds or thousands of listings per source in a single run.

### What it does

- **Shop catalog** - every listing from a shop, plus a shop profile record with location, owner, rating, and review count.
- **Keyword search** - listings matching any search term across the marketplace.
- **Listing detail** - full data for a specific listing: title, price, list price, availability, quantity, rating, review count, description, category, image gallery, and a sample of reviews.
- **Pagination** - shop and search modes walk multiple pages until your `maxResultsPerSource` is reached or the source runs out.
- **Optional enrichment** - turn lightweight shop and search cards into full listing records on demand.

### Input

| Field | Type | Description |
|---|---|---|
| `shops` | array | Shop names to pull listings from. With or without `shop/`, or a full shop URL. Example: `example_shop`. |
| `searchQueries` | array | Keyword searches. Example: `ceramic mug`. |
| `listingUrls` | array | Listing links or IDs to fetch in full detail. Example: `https://www.etsy.com/listing/1234567890/example-title` or `1234567890`. |
| `maxResultsPerSource` | integer | Cap per shop or search query. Default 100. |
| `enrichListings` | boolean | Also open each shop and search listing for full detail. Default off. |
| `includeShopProfile` | boolean | Return a shop profile record in shop mode. Default on. Not billed. |
| `concurrency` | integer | Sources processed in parallel. Default 5. |
| `proxyConfig` | object | Apify proxy. RESIDENTIAL is the default and recommended. |

At least one of `shops`, `searchQueries`, or `listingUrls` is required.

#### Example input

```json
{
  "shops": ["example_shop"],
  "searchQueries": ["ceramic mug"],
  "maxResultsPerSource": 250,
  "enrichListings": false,
  "includeShopProfile": true,
  "concurrency": 3
}
```

### Output

Each item is tagged with a `type` of `listing` or `shop`.

#### Listing

```json
{
  "type": "listing",
  "id": "1234567890",
  "url": "https://www.etsy.com/listing/1234567890/an-example-title",
  "title": "An example handmade ceramic mug",
  "shop": "example_shop",
  "shopUrl": "https://www.etsy.com/shop/example_shop",
  "category": "Home & Living < Kitchen & Dining < Drink & Barware < Mugs",
  "price": 24.0,
  "currency": "USD",
  "listPrice": 30.0,
  "availability": "InStock",
  "quantity": 112,
  "rating": 4.9,
  "reviewCount": 4704,
  "description": "An example listing description.",
  "images": [
    "https://i.example.com/full/example_1.jpg",
    "https://i.example.com/full/example_2.jpg"
  ],
  "thumbnail": "https://i.example.com/full/example_1.jpg",
  "reviews": [
    {
      "author": "Jane Doe",
      "rating": 5,
      "date": "2024-12-19",
      "body": "An example review body."
    }
  ],
  "scrapedAt": "2026-06-17T12:00:00.000Z"
}
```

#### Shop

```json
{
  "type": "shop",
  "name": "example_shop",
  "url": "https://www.etsy.com/shop/example_shop",
  "location": "Arizona, United States",
  "owner": "Jane Doe",
  "slogan": "An example shop slogan",
  "description": "An example shop description.",
  "logo": "https://i.example.com/logo.jpg",
  "banner": "https://i.example.com/banner.jpg",
  "rating": 5,
  "reviewCount": 4704,
  "listingCount": 36,
  "scrapedAt": "2026-06-17T12:00:00.000Z"
}
```

Every field is always present. Unknown values are `null`.

### Use cases

- Build a price and product dataset for a shop or a category for market and competitor analysis.
- Track a competitor's catalog, pricing, and rating over time on a schedule.
- Monitor search results for a keyword to spot new sellers and trending products.
- Collect listings and reviews for research or model training.

### Notes

- A run uses the Apify proxy you select. RESIDENTIAL gives the most reliable results.
- If a source is temporarily unavailable, the item is returned with a generic status (`upstream_unavailable`, `upstream_rate_limit`, or `not_found`) so a single failure never stops the run.
- Pagination depth is bounded by what the source exposes for a given shop or search.
- Shop and search cards carry the core fields (title, price, image). Turn on `enrichListings` for full per-listing detail including description and reviews.

To improve our actors we collect anonymized usage telemetry (run stats and input patterns). No personal account data is collected.

# Actor input Schema

## `shops` (type: `array`):

Shop names to pull listings from. With or without the shop/ prefix, or a full shop URL. Example: example\_shop, https://www.etsy.com/shop/example\_shop.

## `searchQueries` (type: `array`):

Keyword searches to run across the marketplace. Example: ceramic mug, handmade earrings.

## `listingUrls` (type: `array`):

Specific listing links or IDs to fetch in full detail. Example: https://www.etsy.com/listing/1234567890/example-title or 1234567890.

## `maxResultsPerSource` (type: `integer`):

Cap on listings returned per shop or search query. Pagination is walked across multiple pages until this is reached or the source is exhausted. Listing-detail mode always returns one listing per input.

## `enrichListings` (type: `boolean`):

When on, each listing returned by shop and search modes is also opened for its full detail (description, rating, reviews, image gallery). Off by default to keep runs fast and cheap. Listing-detail mode is always full detail.

## `includeShopProfile` (type: `boolean`):

When on, shop mode also returns one profile record per shop with location, owner, rating, and review count. Profile records are not billed.

## `concurrency` (type: `integer`):

How many sources to process in parallel. Higher is faster but puts more load on proxies.

## `proxyConfig` (type: `object`):

Apify proxy. RESIDENTIAL is the default and recommended option for the most reliable results.

## Actor input object example

```json
{
  "shops": [
    "__healthcheck__"
  ],
  "searchQueries": [],
  "listingUrls": [],
  "maxResultsPerSource": 100,
  "enrichListings": false,
  "includeShopProfile": true,
  "concurrency": 5,
  "proxyConfig": {
    "useApifyProxy": true,
    "apifyProxyGroups": [
      "RESIDENTIAL"
    ]
  }
}
```

# 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 = {
    "shops": [
        "__healthcheck__"
    ],
    "searchQueries": [],
    "listingUrls": [],
    "proxyConfig": {
        "useApifyProxy": true,
        "apifyProxyGroups": [
            "RESIDENTIAL"
        ]
    }
};

// Run the Actor and wait for it to finish
const run = await client.actor("goat255/etsy-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 = {
    "shops": ["__healthcheck__"],
    "searchQueries": [],
    "listingUrls": [],
    "proxyConfig": {
        "useApifyProxy": True,
        "apifyProxyGroups": ["RESIDENTIAL"],
    },
}

# Run the Actor and wait for it to finish
run = client.actor("goat255/etsy-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 '{
  "shops": [
    "__healthcheck__"
  ],
  "searchQueries": [],
  "listingUrls": [],
  "proxyConfig": {
    "useApifyProxy": true,
    "apifyProxyGroups": [
      "RESIDENTIAL"
    ]
  }
}' |
apify call goat255/etsy-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "command": "npx",
            "args": [
                "mcp-remote",
                "https://mcp.apify.com/?tools=goat255/etsy-scraper",
                "--header",
                "Authorization: Bearer <YOUR_API_TOKEN>"
            ]
        }
    }
}

```

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/acts/sVkcV5KnEs0WLl9xB/builds/kt0P9H5qCZdJErDY3/openapi.json