# Etsy Search Suggestions Scraper: a-z, questions, CSV/JSON (`tallyrake/etsy-autocomplete-scraper`) Actor

Etsy search-box suggestions as CSV/JSON rows at $0.25 per 1,000 dataset rows: seed, query sent, suggestion, rank, expansion (a-z, question words, prepositions; comparisons and numbers optional), region, language, stable id.

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

## Pricing

from $3.00 / 1,000 result 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/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 Suggestions Scraper: a-z, questions, CSV/JSON

Etsy search-box suggestions as CSV/JSON rows. Give it seed keywords; it requests the suggestions Etsy shows while a buyer or seller types in the search box, for the seed, seed + a to z, question words, and prepositions (comparisons and numbers only if you enable those expansions), for the region you set. One flat row per unique suggestion per seed, each with a stable `id`. Pricing placeholder: $0.25 per 1,000 rows.

Same engine, other search boxes: [Google](https://apify.com/tallyrake/google-autocomplete-scraper), [YouTube](https://apify.com/tallyrake/youtube-autocomplete-scraper), [Amazon](https://apify.com/tallyrake/amazon-autocomplete-scraper), [Bing](https://apify.com/tallyrake/bing-autocomplete-scraper), [DuckDuckGo](https://apify.com/tallyrake/duckduckgo-autocomplete-scraper), [TikTok](https://apify.com/tallyrake/tiktok-autocomplete-scraper), [Pinterest](https://apify.com/tallyrake/pinterest-autocomplete-scraper). Same input shape, same flat rows, one run per engine.

### What you get

| Field | Example |
|---|---|
| `id` | stable per seed, region, language, query and suggestion |
| `seed` | `ceramic mug` (your seed, as typed) |
| `query` | `ceramic mug` (the exact string sent, lowercased) |
| `suggestion` | `ceramic mug handmade` |
| `rank` | `1` (position among keyword suggestions for that query) |
| `expansion` | `direct`, `alphabet`, `question`, `preposition`, `comparison`, `number`, `depth` |
| `modifier` | empty for the seed itself; otherwise `b`, `how`, `for`, `vs` |
| `depth` | `1` or `2` |
| `region` | `US` |
| `language` | `en-US` (the `x-detected-locale` value sent) |
| `engine` | `etsy` |
| `fetchedAt` | ISO timestamp |

Rows are deduplicated per seed (case-insensitive), so a suggestion that appears under several modifiers is counted once, under the first query that produced it.

A direct query for `ceramic mug` on 2026-10-15, US, with the homepage's `version` and `extras`, returned 18 keyword suggestions. The first three were `ceramic mug handmade`, `ceramic mugs`, `ceramic mugs personalized`. The same query without `version` or `extras`, earlier the same day, returned 11, and the literal `ceramic mug` was rank 1. The list moves.

### What this is not

Not listings. Not shops. Not sales data. No prices, no views, no favorites, no search volume. The last row of the dropdown, "find shop names containing …", is a shop search link and is dropped.

### Example input

```json
{
  "keywords": ["ceramic mug"],
  "expansions": ["alphabet", "questions", "prepositions"],
  "depth": 1,
  "region": "US",
  "maxQueriesPerKeyword": 300
}
```

Paste seeds one per line. The default expansions send 52 queries per seed (1 seed + 26 letters + 14 question words + 11 prepositions). Comparisons and numbers are not in that 52. The actor also reads the Etsy homepage once per run for `data-as-version` and `data-as-extras`. That read is not a suggestion query and writes no row.

### Recipes

**Tags for one product.** Seeds: the product phrase. Expansions: alphabet. Depth 1. The suggestions are phrases Etsy completes, in its order.

**Questions buyers type.** Seeds: the product. Expansions: questions and prepositions. Depth 1.

**A wider net.** Depth 2 sends each first-level suggestion back as its own query, still inside `maxQueriesPerKeyword`.

### Reliability and cost

Pricing placeholder: $0.25 per 1,000 dataset rows, plus Apify platform usage. The price is not set on the platform by this folder. Empty queries produce no rows. Every request is paced with a jittered delay (`pacingMs`, default 200 ms). On HTTP 429, 403, or 503 the run rotates its session and retries with backoff.

There is no measured full-expansion run, and there is no fixed number of rows per query. The checked versioned query returned 18 keyword rows. At that size, 52 queries is 936 rows before dedupe ($0.23 at the placeholder price) and the default cap of 300 queries is 5,400 rows before dedupe ($1.35). A shorter list costs less. Deduping lowers the bill. You are billed rows, not queries. The one homepage read per run writes no row.

Proxy default is Apify Proxy with no proxy groups, which is the datacenter pool. Turn groups on only if you want residential.

### Cost limit

If a run reaches the "Maximum total charge per run" you set, it stops in process rather than being aborted by the platform: the run ends with status SUCCEEDED, and the run status message says how many rows were written and how many were found but not written and not billed. Re-running the same input writes and bills the same prefix again, so raise the cap before re-running if you want the rest.

### Bigger jobs

Running thousands of Etsy shop keywords, or need this as a one-off file instead of a run? We build custom exports — any keywords, countries and date ranges, delivered as flat CSV or JSON within 24 hours: https://tallyrake.com/datasets/

### Limits

This is the suggestion list for the region you set, at the time of the run. It carries no search volume. The checked versioned response had 19 JSON rows: 18 keyword suggestions plus one shop-name row, which this actor drops. The page script can paint fewer rows than the JSON contains (`data-autosuggest-num-rows`, default 5, and that attribute was not on the homepage). This actor keeps every keyword row from the JSON. It does not re-apply that display cap. Export CSV for Excel and Google Sheets. Export JSON for pipelines.

`region` `US` was checked (English suggestions for `ceramic mug`). `DE` was checked (`tasse` came back as `tasse personalisiert`, `tasse keramik`, and the rest in German). UK, FR, ES, IT, NL, PL, PT, CA, AU, and JP are sent with the same headers and were not fetched. CA uses `en-US`. AU uses `en-AU`. Those two language tags are untested.

# Actor input Schema

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

One seed per line. Each seed is expanded (see Expansions) and every expanded query is sent to the Etsy search box suggestions endpoint.

## `expansions` (type: `array`):

How to fan each seed out. alphabet: seed + a..z (26 queries). questions: who/what/why/how/when/where/which/is/are/can/does/do/will/should + seed (14). prepositions: seed + for/with/without/to/near/in/on/from/like/after/before (11). comparisons: seed + vs/or/versus/and (4). numbers: seed + 1..5/10/2026 (7). The plain seed is always queried.

## `depth` (type: `integer`):

1 = expand the seeds only. 2 = also send every first-level suggestion back to the suggestions endpoint (capped by Max queries per keyword).

## `maxQueriesPerKeyword` (type: `integer`):

Cap on the number of suggestion requests made per seed, across expansions and depth. The one homepage read per run is not counted here.

## `region` (type: `string`):

Etsy region. Sets the x-detected-locale header and the lang field inside extras. US and DE were checked live; the other codes are sent the same way and were not fetched during the build.

## `dedupe` (type: `boolean`):

Keep the first occurrence of each suggestion per seed keyword (case-insensitive).

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

Apify Proxy, datacenter by default (leave proxy groups empty). The run rotates its session on HTTP 429, 403, or 503. Residential is optional.

## `maxConcurrency` (type: `integer`):

Parallel suggestion requests. 3 is the default; up to 10.

## `pacingMs` (type: `integer`):

Base jittered delay between requests per worker; 0 disables pacing.

## Actor input object example

```json
{
  "keywords": [
    "ceramic mug"
  ],
  "expansions": [
    "alphabet",
    "questions",
    "prepositions"
  ],
  "depth": 1,
  "maxQueriesPerKeyword": 300,
  "region": "US",
  "dedupe": true,
  "proxyConfiguration": {
    "useApifyProxy": true
  },
  "maxConcurrency": 3,
  "pacingMs": 200
}
```

# Actor output Schema

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

All suggestion rows (one per suggestion per seed).

## `csv` (type: `string`):

The same rows as CSV.

# 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("tallyrake/etsy-autocomplete-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("tallyrake/etsy-autocomplete-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 tallyrake/etsy-autocomplete-scraper --silent --output-dataset

```

## MCP server setup

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