# Etsy Keyword Tool & Autocomplete Scraper (`astravalabs/etsy-keyword-research-tool`) Actor

Discover Etsy autocomplete and long-tail keywords from up to 50 seed terms per run. Expand across custom prefixes, preserve Etsy's suggestion rankings, deduplicate results, and control spend with per-seed and whole-run caps.

- **URL**: https://apify.com/astravalabs/etsy-keyword-research-tool.md
- **Developed by:** [astravalabs](https://apify.com/astravalabs) (community)
- **Categories:** E-commerce, SEO tools, Integrations
- **Stats:** 2 total users, 2 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $2.65 / 1,000 etsy keyword suggestions

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 Keyword Research Tool

Get the exact autocomplete suggestions Etsy's own search box shows shoppers — the same dropdown you see typing into etsy.com/search, pulled programmatically for up to 50 seed terms in a single run.

No proxy setup required. No captcha-solving service needed. Proxies are bundled — just provide seed keywords and run.

**Pricing: $2.65 per 1,000 suggestions. No per-run start fee, no compute charges.** You pay for saved suggestions and nothing else. Duplicates are dropped before they reach your dataset, so you never pay for the same keyword twice.

### Quick start

```json
{
  "keywords": ["candle", "mug", "gift"]
}
```

Three seeds, each expanded across the alphabet — roughly 350–380 suggestions per seed, in seconds.

### Why this one

**Batch your seeds.** Pass an array of keywords and get them all in one run. Most Etsy keyword actors take a single keyword per run, which means a separate run — and a separate start fee — for every term you want to research.

**No start fee.** Runs that charge a flat fee before returning anything punish exactly the workflow keyword research demands: many small, exploratory runs. We charge per saved suggestion, full stop.

**Long-tail expansion on by default.** Each seed is also queried followed by every letter (`gift a`, `gift b`, …) and the dropdowns are merged. It's the trick power users do by hand, and it turns `gift` from 14 suggestions into 372. Set `expandPrefixes: false` if you only want the seed's own dropdown.

**Specific seeds expand too.** `handmade candle` yields 238 suggestions, `custom dog painting` yields 271 — 14–27× the base dropdown, whether your seed is one word or four. Many autocomplete scrapers return nothing at all for a multi-word prefix; this one matches what Etsy's own search box shows a shopper mid-type.

**Spend caps that actually bind, on by default.** `maxTotalResults` defaults to 2000 suggestions, so a run can never surprise you no matter how many seeds you paste in. `maxSuggestionsPerSeed` bounds each seed instead. Rows beyond a cap are never saved and never billed — you know your ceiling before you start.

**Every language, no configuration.** Etsy's autocomplete completes the phrase you type, against a global index. Seed it with `kerze` and you get `kerzenständer gold`, `kerzenhalter wand`; seed it with `cadeau` and you get `cadeau nounou`, `cadeau personnalisé`. Nothing to configure — the language of your seed is the language of your results.

### What you get on every row

**`keyword`** — the seed term you provided.

**`suggestion`** — the exact autocomplete string Etsy's search box would show.

**`rank`** — 1-indexed emission order within the seed. A stable sort key, not a score.

**`source_rank`** — 1-indexed position within its own dropdown, i.e. Etsy's ordering. `candle art` is Etsy's **#1** suggestion for `candle a`, so its `source_rank` is 1 even though it's the 14th row of the seed. **This is the relevance signal** — sort by it to find the strongest term surfaced by each query.

**`search_url`** — a ready-to-click Etsy search URL for that suggestion.

**`prefix`** — the expansion character that surfaced this suggestion (empty for the seed's own dropdown; only meaningful when prefix expansion is on).

**`source_query`** — the exact query sent to Etsy that first surfaced this suggestion (the seed itself, or e.g. `handmade candle a`).

**`scraped_at`** — UTC timestamp.

### What you control

| Field | Default | Description |
|---|---|---|
| `keywords` | — | 1–50 seed terms to expand, batched in one run |
| `expandPrefixes` | **true** | Also query each seed followed by every expansion character (`gift a`, `gift b`, …) and merge the dropdowns — 14–27× more long-tail per seed. Set to `false` for just the seed's own dropdown |
| `prefixCharacters` | a–z | Characters appended during expansion; edit to add digits or narrow the set |
| `maxSuggestionsPerSeed` | — | Optional cap on deduplicated suggestions kept per seed — a cost guardrail for expansion |
| `maxTotalResults` | **2000** | Cap on suggestions saved across the whole run. Once hit, remaining queries are skipped — rows beyond the cap are never saved or billed. Raise it for large sweeps |

### Use cases

**Deep long-tail sweeps.** The default. Each seed is pulled followed by every letter (`mushroom lamp a`, `mushroom lamp b`, …) — the same trick power users do by hand, harvesting 14–27× more suggestions per seed in one run.

```json
{
  "keywords": ["mushroom lamp", "cottagecore decor", "linen dress"]
}
```

**Just the dropdown.** Turn expansion off when you want exactly what a shopper sees when they type your seed, and nothing more.

```json
{
  "keywords": ["mushroom lamp"],
  "expandPrefixes": false
}
```

**Bounded spend.** `maxTotalResults` caps the run and defaults to 2000. Raise it for a big sweep, or lower it to hold a run to a known budget.

```json
{
  "keywords": ["mushroom lamp", "cottagecore decor", "linen dress"],
  "maxTotalResults": 500
}
```

Across many seeds, prefer `maxSuggestionsPerSeed` — seeds run in parallel and race for the run-wide budget, so `maxTotalResults` alone doesn't guarantee each seed gets an equal share.

```json
{
  "keywords": ["lamp", "decor", "dress", "candle", "mug"],
  "maxSuggestionsPerSeed": 100
}
```

**Find the strongest term per prefix.** Sort by `source_rank` and filter to `1` to get Etsy's top suggestion for every query it answered — 27 high-confidence terms per expanded seed, one per letter of the alphabet.

**Listing title & tag research.** Rank-ordered suggestions double as a ready-made source of search terms for titles and tags — pulled straight from what shoppers actually type.

**Non-English markets.** Seed in the language you sell in. Etsy completes the phrase you give it, so German seeds return German long-tail and French seeds return French — no locale setting, no separate run per market.

```json
{
  "keywords": ["kerze", "geschenk für sie", "cadeau personnalisé"]
}
```

**Bulk seed sweeps.** Run up to 50 seed variants in one call — each gets its own rank-ordered suggestion set and a per-seed summary.

### Output

Results land in the **default dataset** — export as JSON, CSV, Excel, or JSONL from the Apify console or via API. The dataset holds only suggestion rows (one per suggestion).

Per-seed status is written to the **Key-Value Store** under the key `RUN_REPORT`, in the same order as the input. Each seed reports `status` (`completed`, `capped`, `failed`, or `not_started`), query counts, `suggestions_count`, `completed`, `capped`, and a machine-readable `reason`. The summary separates fully completed, capped, failed, and not-started seeds and records whether a whole-run limit was reached. This makes a cost-capped run visibly different from a full run. Keeping metadata out of the dataset means the dataset stays billable-per-suggestion with no meta rows mixed in.

### Sample row

```json
{
  "keyword": "candle",
  "suggestion": "candle art",
  "rank": 14,
  "source_rank": 1,
  "search_url": "https://www.etsy.com/search?q=candle+art",
  "prefix": "a",
  "source_query": "candle a",
  "scraped_at": "2026-07-05T12:00:00.000000+00:00"
}
```

The 14th row of the `candle` seed, and Etsy's **first** suggestion for `candle a`.

### Companion actors

- [Etsy Listings Scraper](https://apify.com/astravalabs/etsy-scraper) — turn keyword ideas into localized Etsy search results, organic ranks, and sponsored placements.
- [Etsy Product Scraper](https://apify.com/astravalabs/etsy-product-scraper) — enrich selected listing IDs with full product-page, variation, demand, shipping, and policy data.
- [Etsy Shop Catalog Scraper](https://apify.com/astravalabs/etsy-shop-catalog-scraper) — collect every listing from one or more Etsy shops.
- [Etsy Reviews Scraper](https://apify.com/astravalabs/etsy-reviews-scraper) — export complete buyer-review histories for Etsy shops.

### What this Actor does not do

It returns Etsy's autocomplete suggestions — the real search phrases Etsy proposes to shoppers. It does not estimate search volume, competition scores, or listing performance. Those numbers are not published by Etsy, and tools that display them are modelling, not measuring.

***

> ⚠️ Unofficial. This actor is not affiliated with, endorsed by, or sponsored by Etsy, Inc. "Etsy" is a trademark of Etsy, Inc., used here for descriptive purposes only.

# Actor input Schema

## `keywords` (type: `array`):

Seed terms to expand via Etsy's search-box autocomplete. Broad or specific — both expand well.

## `expandPrefixes` (type: `boolean`):

For each seed, also query the seed followed by each expansion character ("gift a", "gift b", …) and merge the dropdowns. Uncovers 14–27× more long-tail suggestions per seed. On by default — turn it off for just the seed's own dropdown, or use the caps below to bound the result count.

## `prefixCharacters` (type: `string`):

Characters appended to each seed when "Expand prefixes" is on (each as " {char}"). Defaults to a–z; edit to add digits or narrow the set. Only used when expansion is enabled.

## `maxSuggestionsPerSeed` (type: `integer`):

Cap the number of (deduplicated) suggestions kept per seed. Cost guardrail for prefix expansion. Leave empty for unlimited.

## `maxTotalResults` (type: `integer`):

Cap the total number of suggestions the run will save and bill for, across every seed. Once reached, remaining queries are skipped — capped rows are never saved and never billed. Defaults to 2000; raise it for large sweeps. With many seeds, which seeds fill the cap is not guaranteed, so prefer maxSuggestionsPerSeed when you want an even split.

## Actor input object example

```json
{
  "keywords": [
    "candle"
  ],
  "expandPrefixes": true,
  "prefixCharacters": "abcdefghijklmnopqrstuvwxyz",
  "maxTotalResults": 2000
}
```

# Actor output Schema

## `suggestions` (type: `string`):

The dataset: one row per suggestion with rank, dropdown rank, and search URL.

## `runReport` (type: `string`):

Per-seed status (query count, suggestions, completed) and run totals.

# 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": [
        "candle"
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("astravalabs/etsy-keyword-research-tool").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": ["candle"] }

# Run the Actor and wait for it to finish
run = client.actor("astravalabs/etsy-keyword-research-tool").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 '{
  "keywords": [
    "candle"
  ]
}' |
apify call astravalabs/etsy-keyword-research-tool --silent --output-dataset

```

## MCP server setup

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

```

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/acts/IC91ej8ZL7pBKaA5n/builds/9ymFPtuieDq6c81YX/openapi.json