# Etsy Search Scraper | Prices, Shops, Ads & Rankings (`genial_candlestand/etsy-search-scraper`) Actor

Get Etsy listings by keyword or category URL: title, price, original price and discount, shop name, shop rating, ad flag, Star Seller and Bestseller badges, and rank in Etsy's search order. Many keywords per run, price, sort and ship-to filters. No login.

- **URL**: https://apify.com/genial_candlestand/etsy-search-scraper.md
- **Developed by:** [Flowo](https://apify.com/genial_candlestand) (community)
- **Categories:** E-commerce, SEO tools
- **Features:** Limited permissions
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $2.03 / 1,000 etsy listings

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.
Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
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.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## 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.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## Etsy Search Scraper | Prices, Shops, Ads & Rankings

![Etsy Search Scraper | Prices, Shops, Ads & Rankings](https://api.apify.com/v2/key-value-stores/Ll7RrWtDkZYOrBvfE/records/etsy-com-product-search-category-listings-banner-6ecb31dd.png)

Get Etsy listings from keyword searches and category pages, one row per listing: title, price with the original price and discount, shop name and shop rating, the ad flag, Star Seller and Bestseller badges, and the listing's rank in Etsy's results. Add many keywords and category or search URLs in one run, filter by price, sort order, ship-to country and free shipping. No Etsy login or API key is needed.

### What does Etsy Search Scraper do?

You give it Etsy keywords (for example "ceramic mug") and/or Etsy URLs: category pages (`/c/jewelry/rings`), search pages (`/search?q=...`) or market pages (`/market/ceramic_mug`). It returns the listings in the order Etsy shows them to a US shopper, with a `position` rank, the ad flag and the total number of results Etsy reports. It is built for Etsy sellers checking keyword rankings and ads, product researchers comparing prices and badges in a category, and analysts who need many keywords or categories in one call.

### How to scrape Etsy search results and categories

![Etsy Search Scraper output example: Image, Title, Price, Currency, Original price](https://api.apify.com/v2/key-value-stores/Ll7RrWtDkZYOrBvfE/records/etsy-com-product-search-category-listings-output-1a9d5228.png)

![How Etsy Search Scraper works: Sends each keyword through Etsy's own search request as a US shopper; Reads category pages and their structured data for shop names; Retries a blocked search page on up ](https://api.apify.com/v2/key-value-stores/Ll7RrWtDkZYOrBvfE/records/etsy-com-product-search-category-listings-how-9ecb001f.png)

1. Open the actor in Apify Console.
2. Enter one or more keywords in **Search keywords**, and/or paste Etsy category or search URLs into **Etsy category or search URLs**.
3. Set **Max listings per keyword or URL** and **Max listings in total**.
4. Optionally choose a sort order, a price range, a ship-to country, free shipping only, or turn off ads for an organic-only ranking.
5. Keep the default residential proxy and click **Start**.
6. Download the listings as JSON, CSV or Excel, or open the **Overview** view in the dataset.

### How much does it cost to scrape Etsy?

Price per event by Apify plan:

| Event | Free | Bronze | Silver | Gold and above |
|---|---|---|---|---|
| Etsy listing | $2.90 per 1,000 | $2.61 per 1,000 | $2.32 per 1,000 | $2.03 per 1,000 |
| Actor start | $0.00005 | $0.00005 | $0.00005 | $0.00005 |

A test run with the API example input below returned 160 rows in 20 s.

The actor is priced per listing. One paid `listing` event is one Etsy listing saved to the dataset. Duplicates (ads repeated on later pages) and ads removed by **Include ads: off** are not saved and not charged. The proxy is included: there are no separate residential proxy usage fees. A tiny start fee is charged once per run.

| Scenario | Listing events | Cost on the Free plan |
|---|---|---|
| 1 keyword, 100 listings | 100 | about $0.29 |
| 1 keyword + 1 category, 100 each (the prefilled input) | 200 | about $0.58 |
| 10 keywords, 100 listings each | 1,000 | about $2.90 |
| 5 categories, 1,000 listings each | 5,000 | about $14.50 |

### Input

![Etsy Search Scraper input example: Search keywords, Etsy category or search URLs, Max listings per keyword or URL, Max listings in total, Sort by, Free shipping only, Include ads](https://api.apify.com/v2/key-value-stores/Ll7RrWtDkZYOrBvfE/records/etsy-com-product-search-category-listings-input-7d0ab631.png)

| Field | What it does |
|---|---|
| `queries` | Etsy keywords, one per line. Each keyword is searched in Etsy's own search ranking. |
| `startUrls` | Etsy category (`/c/...`), search (`/search?q=...`) or market (`/market/...`) URLs. Listing and shop URLs are not supported. |
| `maxItemsPerQuery` | Listings per keyword or URL (default 100). |
| `maxItems` | Listings per run in total (default 1000). |
| `sortBy` | `most_relevant` (default), `price_asc`, `price_desc` or `date_desc`. |
| `minPrice` / `maxPrice` | Price range in USD. |
| `shipTo` | 2-letter country code, e.g. `GB`; only listings that ship there. |
| `freeShipping` | Only listings with free shipping. |
| `includeAds` | Keep sponsored listings (default on). |
| `proxyConfiguration` | Apify residential proxy, US (default). |

Give `queries`, `startUrls` or both. Example input:

```json
{
  "queries": ["ceramic mug", "personalized necklace"],
  "startUrls": [{ "url": "https://www.etsy.com/c/jewelry/rings" }],
  "maxItemsPerQuery": 200,
  "maxItems": 1000,
  "sortBy": "most_relevant",
  "includeAds": true
}
```

### What data can you extract from Etsy?

| Field | Description |
|---|---|
| `id`, `url`, `title`, `imageUrl` | Listing ID, listing page, title and main image |
| `price`, `currency` | Current (sale) price and its currency code (`USD` in our runs); both are empty when a card shows no price |
| `originalPrice`, `discountPercent` | Price before the discount and the discount; only when on sale |
| `shopId`, `shopName`, `shopUrl` | The seller's shop |
| `shopRating`, `shopReviewsCount` | The shop's average rating and review count, as shown on the card |
| `shopSales`, `shopYearsOnEtsy`, `shipsFrom` | Seller preview data, on some keyword rows |
| `isAd`, `isStarSeller`, `isBestseller`, `isPopularNow`, `isFreeShipping`, `isDigitalDownload` | Ad flag and card badges (always true or false) |
| `sourceType`, `query`, `category`, `sourceUrl` | Which keyword or category produced the row, and the Etsy page it was found on |
| `page`, `position`, `totalResults` | Result page, rank among all cards shown (ads included), total results Etsy reports |
| `scrapedAt` | When the row was extracted |

A real row from the `jewelry/rings` category (shortened):

```json
{
  "id": "4467406339",
  "url": "https://www.etsy.com/listing/4467406339/41-carat-e-color-vvs2-clarity-igi",
  "title": "4.1 carat E Color VVS2 Clarity IGI Certified Marquise Cut Lab Grown Diamond Solitaire Hidden Halo Engagement Ring 14k Yellow Gold",
  "price": 3744.78,
  "currency": "USD",
  "originalPrice": 5349.68,
  "discountPercent": 30,
  "shopId": "21916549",
  "shopName": "ForeverForLove",
  "shopUrl": "https://www.etsy.com/shop/ForeverForLove",
  "shopRating": 4.82,
  "shopReviewsCount": 3435,
  "isAd": true,
  "isStarSeller": true,
  "isBestseller": false,
  "isFreeShipping": true,
  "sourceType": "category",
  "category": "jewelry/rings",
  "sourceUrl": "https://www.etsy.com/c/jewelry/rings",
  "page": 1,
  "position": 1,
  "totalResults": 40657,
  "scrapedAt": "2026-11-08T11:38:15.102Z"
}
```

### Use cases

- **Etsy SEO and rank tracking:** see where listings rank for a keyword (`position`) and which shops advertise on it (`isAd`).
- **Organic ranking only:** turn off ads to get Etsy's organic order, for example the cheapest leather wallets that ship free to the UK.
- **Product and price research:** compare prices, discounts and Bestseller badges within a category and a price band, e.g. kitchen and dining items at $20–50.
- **Competitor and supplier scouting:** collect shop names, shop ratings and Star Seller status for a niche.
- **Bulk research by AI agents:** mix several keywords and categories in one run with one row per listing.

### Limitations

- Data comes from search and category cards, not listing pages. In-cart counts, "bought in 24 hours", favorites, tags and descriptions are not returned.
- `shopRating` and `shopReviewsCount` are the **shop's** rating and review count, because that is what Etsy cards show; there is no per-listing rating.
- `shopName` and `shopUrl` are on almost every category row but only on about 20% of keyword rows (Etsy omits the shop name on lazily loaded cards). `shopId` is on almost every row.
- `shopSales`, `shopYearsOnEtsy` and `shipsFrom` come from Etsy's seller preview and are filled on only a small share of keyword rows, never on category rows.
- The actor searches as a US shopper, so `currency` was `USD` on every row in our runs, even with `shipTo` set to another country; `price` and `currency` can be empty when a card shows no price.
- Depth follows Etsy: about 20 pages (roughly 1,000–1,200 listings) for most keywords, up to 250 pages for broad keywords, some sort orders and categories.
- Keyword search uses Etsy's internal search request; if Etsy changes it, keyword runs may fail until the actor is updated.

### Tips and troubleshooting

- **Keep the residential proxy.** Keywords, search URLs and market URLs need Apify `RESIDENTIAL` proxy; the actor stops with an input error otherwise. Category-only runs also work with datacenter proxy.
- **Get more listings** by raising `maxItemsPerQuery` and `maxItems`; the actor stops at Etsy's last page.
- **Paste a search URL from your browser** to keep its keyword, sort, price, ship-to and free-shipping settings. A parameter in the URL wins over the form field; other URL parameters (e.g. attribute filters) are ignored with a warning.
- **Fewer rows than expected?** With `includeAds` off, removed ads leave gaps in `position` and are not counted. Check the log: a blocked page is retried on 3 fresh sessions, and a page that still fails is named in a warning while the other rows are kept.
- `minPrice` must not be greater than `maxPrice`, and `shipTo` must be a real 2-letter country code; otherwise the run stops before any request.
- Localized URLs such as `/uk/c/jewelry/rings` are accepted and scraped as the US page.

### API, MCP and integrations

Run the actor from your code with the same JSON input as in Console. Your API token is in [Console → Settings → API & Integrations](https://console.apify.com/settings/integrations).

**Python** (`pip install apify-client`):

```python
from apify_client import ApifyClient

client = ApifyClient("YOUR_APIFY_TOKEN")
run = client.actor("genial_candlestand/etsy-search-scraper").call(run_input={
    "queries": ["ceramic mug"],
    "startUrls": [{"url": "https://www.etsy.com/c/jewelry/rings"}],
    "maxItemsPerQuery": 80,
})
for item in client.dataset(run["defaultDatasetId"]).iterate_items():
    print(item)
```

**Node.js** (`npm install apify-client`):

```js
import { ApifyClient } from 'apify-client';

const client = new ApifyClient({ token: 'YOUR_APIFY_TOKEN' });
const run = await client.actor('genial_candlestand/etsy-search-scraper').call({
    "queries": ["ceramic mug"],
    "startUrls": [{"url": "https://www.etsy.com/c/jewelry/rings"}],
    "maxItemsPerQuery": 80,
});
const { items } = await client.dataset(run.defaultDatasetId).listItems();
console.log(items);
```

**HTTP** — one request runs the actor and returns the results (runs up to 5 minutes; longer ones: [run asynchronously](https://docs.apify.com/api/v2/act-runs-post)):

```bash
curl -X POST "https://api.apify.com/v2/acts/genial_candlestand~etsy-search-scraper/run-sync-get-dataset-items?token=YOUR_APIFY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"queries":["ceramic mug"],"startUrls":[{"url":"https://www.etsy.com/c/jewelry/rings"}],"maxItemsPerQuery":80}'
```

**AI agents (MCP).** Add the actor as a tool of the [Apify MCP server](https://docs.apify.com/platform/integrations/mcp). Claude Code:

```bash
claude mcp add --transport http apify "https://mcp.apify.com?tools=genial_candlestand/etsy-search-scraper"
```

Claude Desktop, Cursor or VS Code: `{"mcpServers": {"apify": {"url": "https://mcp.apify.com?tools=genial_candlestand/etsy-search-scraper"}}}`. Then ask, for example:

- "Find the top 200 Etsy listings for ceramic mug and show which ones are ads"
- "List Etsy kitchen and dining items priced 20 to 50 USD with shop names and shop ratings"
- "Get the cheapest organic Etsy results for leather wallet that ship free to the UK"

**Integrations.** Run it on a schedule with [Apify Schedules](https://docs.apify.com/platform/schedules) and send the results to Google Sheets, Slack, Zapier, Make, n8n or your webhook — see [Apify integrations](https://docs.apify.com/platform/integrations).

### FAQ

**Is it legal to scrape Etsy?**<br>
The actor collects only publicly visible listing data from Etsy search and category pages, without logging in. It returns no personal data beyond the shop details Etsy shows publicly. You are responsible for how you use the data; check Etsy's terms and the laws that apply to you.

**Does the rating belong to the listing or the shop?**<br>
To the shop. Etsy search and category cards show the shop's average rating and review count, so the fields are named `shopRating` and `shopReviewsCount`.

**Is the order the same as on Etsy?**<br>
Yes for keywords: the actor uses Etsy's own search request, and `position` counts every card Etsy served, ads included, across pages.

**Can I scrape a single listing or a shop page?**<br>
No. Only category, search and market URLs are supported; listing and shop URLs are rejected with an input error.

**How is it different from other Etsy scrapers?**<br>
It takes keywords and category URLs in the same run, follows Etsy's real search ranking with an ad flag and an organic-only switch, pages until Etsy's last page instead of a fixed cap, and includes the proxy in the per-listing price. The leading Etsy listings actor charges $8 per 1,000 listings; this one charges $2.90 on the Free plan.

### Also useful

- [eBay Search Scraper](https://apify.com/genial_candlestand/ebay-search-scraper-listings-prices) — compare the same products on eBay: listing prices and sellers by keyword
- [eBay Sold Listings Scraper](https://apify.com/genial_candlestand/ebay-sold-listings-scraper) — check what similar items actually sold for on eBay, with sold dates and shipping
- [Pinterest Search Scraper](https://apify.com/genial_candlestand/pinterest-search-scraper) — find trending pins and images for the same handmade product keywords
- [Google Trends Scraper](https://apify.com/genial_candlestand/google-trends-scraper) — check search interest over time and by region for your Etsy keywords
- [Amazon Best Sellers Scraper](https://apify.com/genial_candlestand/amazon-best-sellers-scraper) — see the top products on Amazon stores for the same product category

# Actor input Schema

## `queries` (type: `array`):

Etsy keywords, one per line, e.g. ceramic mug. Each keyword returns listings in Etsy's own search order, ads included. Needs the residential proxy (the default). Give keywords, URLs or both.

## `startUrls` (type: `array`):

Etsy category pages (https://www.etsy.com/c/jewelry/rings), search pages (https://www.etsy.com/search?q=mug\&order=price_asc, their keyword, sort, price, ship-to and free-shipping settings are used) or market pages (/market/ceramic_mug, run as a keyword). Listing and shop URLs are not supported.

## `maxItemsPerQuery` (type: `integer`):

Stop each keyword or URL after this many listings. One page has about 48–64 listings; Etsy shows about 20 pages for most keywords and up to 250 for broad keywords and categories. The actor stops at the last page.

## `maxItems` (type: `integer`):

Stop the whole run after this many listings across all keywords and URLs.

## `sortBy` (type: `string`):

Etsy's order of results, for keywords and category URLs. A search URL with its own order= keeps it.

## `minPrice` (type: `number`):

Only listings priced at or above this, in US dollars. Must not be greater than Max price. Applies to keywords and category URLs.

## `maxPrice` (type: `number`):

Only listings priced at or below this, in US dollars. Must not be less than Min price. Applies to keywords and category URLs.

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

Only listings that ship to this country, as a 2-letter ISO code, e.g. US, GB, DE. Prices stay in USD. Leave empty for all listings.

## `freeShipping` (type: `boolean`):

Only listings with free shipping (to the Ships to country when set).

## `includeAds` (type: `boolean`):

Keep sponsored listings (isAd = true). Turn off for the organic ranking only; removed ads are not charged and leave gaps in position.

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

Keyword and search-URL scraping needs Apify RESIDENTIAL proxy (the default; the country is set to US). Category URLs also work with datacenter proxy.

## Actor input object example

```json
{
  "queries": [
    "ceramic mug"
  ],
  "startUrls": [
    {
      "url": "https://www.etsy.com/c/jewelry/rings"
    }
  ],
  "maxItemsPerQuery": 100,
  "maxItems": 1000,
  "sortBy": "most_relevant",
  "freeShipping": false,
  "includeAds": true,
  "proxyConfiguration": {
    "useApifyProxy": true,
    "apifyProxyGroups": [
      "RESIDENTIAL"
    ],
    "apifyProxyCountry": "US"
  }
}
```

# Actor output Schema

## `results` (type: `string`):

All listings, one row per listing per keyword or URL

## `overview` (type: `string`):

Listings with the most useful fields

# 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 = {
    "queries": [
        "ceramic mug"
    ],
    "startUrls": [
        {
            "url": "https://www.etsy.com/c/jewelry/rings"
        }
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("genial_candlestand/etsy-search-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 = {
    "queries": ["ceramic mug"],
    "startUrls": [{ "url": "https://www.etsy.com/c/jewelry/rings" }],
}

# Run the Actor and wait for it to finish
run = client.actor("genial_candlestand/etsy-search-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 '{
  "queries": [
    "ceramic mug"
  ],
  "startUrls": [
    {
      "url": "https://www.etsy.com/c/jewelry/rings"
    }
  ]
}' |
apify call genial_candlestand/etsy-search-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,genial_candlestand/etsy-search-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/JrKeN64S7cdApczRD/builds/yrw9ozH9r2esgrhck/openapi.json
