# Etsy Keyword Research Tool - Ranked Search Suggestions (`vonsensey/etsy-keyword-research-tool`) Actor

Etsy's own search suggestions as data, in the order Etsy ranks them. Expand any seed with buyer-intent modifiers and an A-Z sweep to get hundreds of real shopper phrases, each with the rank Etsy gave it. Ten Etsy locales. Pay per keyword, no run-start fee.

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

## Pricing

from $5.00 / 1,000 keywords

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 Keyword Research Tool - Ranked Search Suggestions

<table style="border-collapse:collapse;width:100%;margin:0 0 4px">
<tr><td colspan="3" style="padding:9px 12px;background:#0B6E75;border:1px solid #0B6E75"><span style="color:#FFFFFF;font-weight:700;font-size:13px;letter-spacing:.3px">Etsy Research Suite</span><span style="color:#CFF0F2;font-size:12px"> &nbsp;&bull;&nbsp; 10 Actors, one codebase, one listing billed once</span></td></tr>
<tr><td style="padding:9px 12px;border:1px solid #E5E7EB;background:#FFFFFF;vertical-align:top;width:33%"><a href="https://apify.com/vonsensey/etsy-scraper" style="color:#111827;font-weight:700;font-size:13px;text-decoration:none">Etsy Scraper API</a><br><span style="color:#6B7280;font-size:11px">Listings, Prices, Tags &amp; Keywords</span></td><td style="padding:9px 12px;border:1px solid #E5E7EB;background:#FFFFFF;vertical-align:top;width:33%"><a href="https://apify.com/vonsensey/etsy-product-research-tool" style="color:#111827;font-weight:700;font-size:13px;text-decoration:none">Etsy Product Research Tool</a><br><span style="color:#6B7280;font-size:11px">Demand, Price &amp; Tag Data</span></td><td style="padding:9px 12px;border:1px solid #E5E7EB;background:#ECFDF5;vertical-align:top;width:33%"><span style="color:#0B6E75;font-weight:700;font-size:13px">Etsy Keyword Research Tool</span><br><span style="color:#0B6E75;font-size:11px;font-weight:600">&#10148; You are here</span></td></tr>
<tr><td style="padding:9px 12px;border:1px solid #E5E7EB;background:#FFFFFF;vertical-align:top;width:33%"><a href="https://apify.com/vonsensey/etsy-seo-tool" style="color:#111827;font-weight:700;font-size:13px;text-decoration:none">Etsy SEO Tool</a><br><span style="color:#6B7280;font-size:11px">Tags, Titles &amp; Keywords That Rank</span></td><td style="padding:9px 12px;border:1px solid #E5E7EB;background:#FFFFFF;vertical-align:top;width:33%"><a href="https://apify.com/vonsensey/etsy-long-tail-keywords-generator" style="color:#111827;font-weight:700;font-size:13px;text-decoration:none">Etsy Long Tail Keywords Generator</a><br><span style="color:#6B7280;font-size:11px">A-Z Suggestions</span></td><td style="padding:9px 12px;border:1px solid #E5E7EB;background:#FFFFFF;vertical-align:top;width:33%"><a href="https://apify.com/vonsensey/etsy-competitor-research-tool" style="color:#111827;font-weight:700;font-size:13px;text-decoration:none">Etsy Competitor Research Tool</a><br><span style="color:#6B7280;font-size:11px">Track Rival Shops</span></td></tr>
<tr><td style="padding:9px 12px;border:1px solid #E5E7EB;background:#FFFFFF;vertical-align:top;width:33%"><a href="https://apify.com/vonsensey/etsy-shop-analyzer-api" style="color:#111827;font-weight:700;font-size:13px;text-decoration:none">Etsy Shop Analyzer API</a><br><span style="color:#6B7280;font-size:11px">Prices, Tags &amp; Bestsellers</span></td><td style="padding:9px 12px;border:1px solid #E5E7EB;background:#FFFFFF;vertical-align:top;width:33%"><a href="https://apify.com/vonsensey/etsy-price-tracker-api" style="color:#111827;font-weight:700;font-size:13px;text-decoration:none">Etsy Price Tracker API</a><br><span style="color:#6B7280;font-size:11px">Monitor Prices on a Schedule</span></td><td style="padding:9px 12px;border:1px solid #E5E7EB;background:#FFFFFF;vertical-align:top;width:33%"><a href="https://apify.com/vonsensey/etsy-tags-scraper" style="color:#111827;font-weight:700;font-size:13px;text-decoration:none">Etsy Tags Scraper</a><br><span style="color:#6B7280;font-size:11px">All 13 Tags From Any Listing</span></td></tr>
<tr><td style="padding:9px 12px;border:1px solid #E5E7EB;background:#FFFFFF;vertical-align:top;width:33%"><a href="https://apify.com/vonsensey/etsy-print-on-demand-research-tool" style="color:#111827;font-weight:700;font-size:13px;text-decoration:none">Etsy Print on Demand Research</a><br><span style="color:#6B7280;font-size:11px">Digital &amp; POD Niches</span></td></tr>
</table>

**More from this account:** [YouTube Transcript Suite](https://apify.com/vonsensey/youtube-transcript-scraper) · [Website Contact & Email Suite](https://apify.com/vonsensey/website-contact-email-extractor) · [Career Site & ATS Jobs Suite](https://apify.com/vonsensey/career-page-job-postings-scraper-api) · [Google News Suite](https://apify.com/vonsensey/google-news-scraper-api) · [Keyword Research Suite](https://apify.com/vonsensey/google-keyword-ideas-scraper) · [Shopify Store Intelligence Suite](https://apify.com/vonsensey/shopify-store-leads-scraper) · [eBay Data Suite](https://apify.com/vonsensey/ebay-scraper-api) · [Amazon Reviews Suite](https://apify.com/vonsensey/amazon-reviews-scraper-api) · [Reddit](https://apify.com/vonsensey/reddit-scraper-posts-comments-api) · [Meta Ad Library](https://apify.com/vonsensey/facebook-ads-library-scraper-meta-ad-api) · [Vinted](https://apify.com/vonsensey/vinted-scraper-api) · [Trustpilot Review Intelligence Suite](https://apify.com/vonsensey/trustpilot-reviews-scraper) · [App Store & Google Play Reviews Suite](https://apify.com/vonsensey/app-store-google-play-reviews-scraper) · [YouTube Comments Intelligence Suite](https://apify.com/vonsensey/youtube-comments-scraper) · [Telegram Channel Intelligence Suite](https://apify.com/vonsensey/telegram-channel-scraper-api) · [Business Reviews Suite](https://apify.com/vonsensey/business-reviews-aggregator-scraper-api) · [Google Trends Suite](https://apify.com/vonsensey/google-trends-scraper) · [Amazon Product Data Suite](https://apify.com/vonsensey/amazon-product-scraper-api) · [Nordic Marketplaces Suite](https://apify.com/vonsensey/dba-dk-scraper-api) · [Google Sheets Suite](https://apify.com/vonsensey/google-sheets-scraper-api) · [TikTok Suite](https://apify.com/vonsensey/tiktok-scraper-api) · [Snapchat Suite](https://apify.com/vonsensey/snapchat-scraper-api) · [LinkedIn Public Data Suite](https://apify.com/vonsensey/linkedin-scraper-api) · [Instagram Suite](https://apify.com/vonsensey/instagram-posts-scraper-api) · [Contact Validation Suite](https://apify.com/vonsensey/email-verifier-validator-api) · [Google Maps Suite](https://apify.com/vonsensey/google-maps-reviews-scraper-api) · [X / Twitter](https://apify.com/vonsensey/tweet-scraper)

Etsy's own search suggestions as data, in the order Etsy ranks them. Expand any seed with buyer-intent modifiers and an A-Z sweep to get hundreds of real shopper phrases, each with the rank Etsy gave it. Ten Etsy locales. Pay per keyword, no run-start fee.

**No Etsy account. No API key. No run-start fee — a run that finds nothing costs nothing.**

***

### What you get

| Field | What it is |
|---|---|
| `keyword` | A phrase Etsy itself suggests to shoppers |
| `etsyRank` | Where Etsy placed it, 1 = first. Etsy's own ordering, **not an invented search volume** |
| `seed` | The term it was expanded from |
| `source` | How it was found: `seed`, `modifier`, `alphabet` or `recursive` |
| `categories` | Etsy categories attached to the phrase, when Etsy supplies any |
| `locale` | Which Etsy storefront it was read in |

Need the listings behind those keywords too? Set `mode` to **Search Etsy by keyword** and every row above is replaced by a full product record — price, favourites, views, bestseller flag and all 13 tags.

#### Four kinds of row, and only two of them cost anything

| Row | `type` | Charged |
|---|---|---|
| An Etsy listing | `listing` | yes |
| An Etsy keyword suggestion | `keyword` | yes |
| A shop summary aggregated from its listings | `shop` | **free** |
| The coverage report for each term | `coverage` | **free** |
| Anything that could not be served | `error` | **free** |

***

### Pricing

| Plan tier | 1,000 listings | 1,000 keywords |
|---|---:|---:|
| FREE | $20.00 | $10.00 |
| BRONZE | $16.70 | $8.40 |
| SILVER | $12.70 | $6.40 |
| **GOLD** | **$10.00** | **$5.00** |
| PLATINUM | $9.30 | $4.70 |
| DIAMOND | $8.70 | $4.40 |

The Store card shows the **GOLD** tier. There is **no run-start fee** on this Actor, and no
per-page or per-request charge — you pay for rows you keep and nothing else.

**What is free, always:** a listing that no longer resolves on Etsy, a listing excluded by
your own price / bestseller / digital filters, every error row, every shop summary, and the
coverage report. Set `maxCostUsd` and the run stops cleanly the moment the next row would
cross your ceiling — and still writes its coverage rows so you know where it got to.

***

### Try it

```json
{
  "mode": "keywords",
  "keywordSeeds": [
    "personalized gift"
  ],
  "maxKeywords": 500,
  "keywordModifiers": true,
  "keywordAlphabet": true
}
```

That is this Actor's default input — press **Run** and you get ranked Etsy keywords straight away.

### Worked recipes

#### Hundreds of long-tail phrases from one seed

```json
{
  "mode": "keywords",
  "keywordSeeds": ["wedding gift"],
  "keywordAlphabet": true,
  "keywordModifiers": true,
  "maxKeywords": 1000
}
```

An A–Z sweep plus twenty buyer-intent shapes, each phrase carrying the rank Etsy gives it.

#### The same niche in another market

```json
{
  "mode": "keywords",
  "keywordSeeds": ["schmuck"],
  "locale": "de"
}
```

German shoppers do not search the way US shoppers do, and Etsy's suggestions reflect that.

***

### Honest limits

We would rather tell you these up front than have you find them out on your own money.

- **One search term returns roughly 100 listings** before Etsy's results for that exact
  phrase run out. Switch on `expandWithKeywords` to sweep a niche properly. Every run
  writes a free `coverage` row saying whether it stopped because Etsy ran out
  (`exhausted`) or because it hit your own cap (`cappedByRun`) — so you never have to guess.
- **No review text, and no shop lifetime sales or follower counts.** Etsy does not publish
  those, so this Actor does not return them and does not pretend to. The shop summary is
  aggregated from the listings the run actually found, and says so.
- **`etsyRank` is an ordinal, not a search volume.** Etsy publishes no volumes. We give you
  Etsy's own ordering and refuse to invent a number.
- **`views` is only as good as Etsy's own publishing of it** — Etsy shows it on some
  listings and not others. Where it is absent the field is `null`, never a guess.

***

### Output example

```json
{
  "type": "listing",
  "listingId": 4472929892,
  "url": "https://www.etsy.com/listing/4472929892",
  "title": "Personalized Handmade Leather Wallet, Slim Front Pocket, Minimalist Bifold",
  "priceUsd": 31,
  "currency": "USD",
  "favorites": 105,
  "views": 2841,
  "isBestseller": false,
  "quantity": 23,
  "tags": ["personalized wallet", "wallet", "slim wallet", "minimalist wallet", "gift for him"],
  "materials": ["leather"],
  "shopName": "CordovanLeather",
  "categoryPath": "bags_and_purses.wallets_and_money_clips.wallets",
  "isDigital": false,
  "whenMade": "made_to_order",
  "shipsFromCountry": "US",
  "imageCount": 12,
  "createdAt": "2026-08-05T18:03:14.000Z",
  "foundVia": "personalized leather wallet"
}
```

***

### Legal

This is an **unofficial** tool. It is not affiliated with, endorsed by, or connected to Etsy,
Inc. in any way, and "Etsy" is a trademark of its owner, used here only to describe what the
Actor reads. It collects **publicly visible listing information only** — the same pages any
shopper can see without signing in. It does not access private data, buyer information,
messages, or anything behind a login. You are responsible for using the data you collect in
line with Etsy's terms and with applicable law in your jurisdiction.

### Use it from n8n, MCP, the API or a schedule

Built to be called by a workflow, not only from the Store form. The Actor is `vonsensey/etsy-keyword-research-tool`; every snippet below sends `{}`, which runs the defaults shown on the form — replace it with your own input.

#### n8n

Install the **Apify** community node (`@apify/n8n-nodes-apify` under *Settings → Community Nodes*, or search "Apify" on n8n Cloud). Add **Apify → Run Actor** with Actor `vonsensey/etsy-keyword-research-tool` and your input JSON, then **Apify → Get Dataset Items** on the run's `defaultDatasetId` and pipe the rows anywhere. For scheduled runs, the **On new Apify Event** trigger fires when a run of this Actor finishes.

#### MCP (Claude, Cursor, VS Code, any MCP client)

```json
{
  "mcpServers": {
    "apify": {
      "url": "https://mcp.apify.com?tools=vonsensey/etsy-keyword-research-tool",
      "headers": {
        "Authorization": "Bearer <YOUR_APIFY_TOKEN>"
      }
    }
  }
}
```

Your agent then calls `vonsensey/etsy-keyword-research-tool` as a tool with the same input the form takes and reads the dataset back.

#### REST API (one call, rows in the response)

```bash
curl -X POST "https://api.apify.com/v2/acts/vonsensey~etsy-keyword-research-tool/run-sync-get-dataset-items?token=$APIFY_TOKEN" \
  -H "Content-Type: application/json" -d '{}'
```

#### Python

```python
from apify_client import ApifyClient
client = ApifyClient("<YOUR_APIFY_TOKEN>")
run = client.actor("vonsensey/etsy-keyword-research-tool").call(run_input={})
for row in client.dataset(run["defaultDatasetId"]).iterate_items():
    print(row)
```

#### JavaScript

```js
import { ApifyClient } from 'apify-client';
const client = new ApifyClient({ token: process.env.APIFY_TOKEN });
const run = await client.actor('vonsensey/etsy-keyword-research-tool').call({});
const { items } = await client.dataset(run.defaultDatasetId).listItems();
```

#### Make, Zapier, LangChain, CrewAI

The Apify app in **Make** and **Zapier** has a *Run an Actor* module: pick `vonsensey/etsy-keyword-research-tool`. In **LangChain** and **CrewAI** the Apify tool wrappers take the same Actor id. A daily **schedule** needs nothing but the Console: *Schedules → Create → this Actor → cron*, and the dataset fills on its own.

> **Run it without configuring anything** — [Etsy keyword research from a seed term](https://apify.com/vonsensey/etsy-keyword-research-tool/examples/etsy-keywords-for-a-seed-term), a ready-made example you can start as-is or copy.

### Use cases

- **Validate a product before you make it.** Pull every listing in the niche you are considering, sort by favourites, and see what the top twenty charge and which tags they use — before you buy materials.
- **Price against the shops you actually compete with.** Every row carries a USD price and the shop behind it, so you get a real price band instead of eyeballing the first page.
- **Fix listings nobody is finding.** Etsy gives every listing 13 tags and they are the biggest lever in Etsy search. Pull the tags of the listings that already rank for your term and compare them with your own.
- **Watch prices and stock on a schedule.** Put a watchlist on a daily run and keep the history. There is no run-start fee, so a day when nothing changed costs nothing.

### Run it on a schedule

A one-off pull answers a question; a schedule answers it every day without you. Open **Schedules** in the Apify Console, point a cron at this Actor, and the dataset keeps filling on its own — no server, no cron box, no babysitting. Everything here is built to be re-run: you are billed per listing delivered, and the FAQ below says exactly what a scheduled run that finds nothing new costs.

### FAQ

#### Do I need an Etsy account or an API key?

No. Give it a search term, a shop name or a listing URL and press Run. Nothing to register, no key to paste.

#### How many listings can I get for one search term?

A single search term returns roughly 100 listings before Etsy's results for that exact phrase run out. That is a property of the search, not a limit we impose — which is why **Expand each term with Etsy's own suggestions** exists: it turns one term into dozens of related Etsy-ranked queries and sweeps a whole niche instead of one page of it. A free coverage row on every run tells you which of the two stopped you.

#### What am I actually charged for?

Only rows you keep. A listing that no longer resolves, a listing your price or bestseller filter excludes, an error row, a shop summary and the coverage report are all free — and there is no run-start fee, so a run that finds nothing costs nothing.

#### Does it give me Etsy search volumes?

No, and be careful of anything that says it does — Etsy does not publish search volumes. What you get is Etsy's own suggestion ranking, the order Etsy puts phrases in when it autocompletes for a shopper. That is a real signal, and it is reported as a rank rather than dressed up as a number of searches.

#### Can I get Etsy reviews or a shop's total sales?

No. Etsy does not expose review text or a shop's lifetime sales and follower counts publicly, so this does not return them and does not pretend to. What you do get is a shop profile aggregated from that shop's listings: price range and median, total favourites, bestseller count, categories and most-used tags.

#### Can I export to CSV, JSON or Excel?

Yes. Every run writes a dataset you can export in one click from the Console, or pull from the API as JSON, CSV, XLSX or JSONL.

***

Something wrong, or a field you need that is missing? Open an issue on the **Issues** tab — it is read and it gets fixed. If this saved you time, a rating on the Store page helps the next person find it.

# Actor input Schema

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

Search Etsy by keyword, pull specific listings you already have URLs for, analyse a shop's listings, or research keywords only. Every mode returns the same listing shape, so you can change your mind without changing your pipeline.

## `searchTerms` (type: `array`):

What to search Etsy for, one term per line — for example 'personalized leather wallet'. Used when mode is 'Search Etsy by keyword'. Each term is searched separately and results are deduplicated across all of them.

## `shopNames` (type: `array`):

Etsy shop names to analyse, one per line — the name as it appears in etsy.com/shop/NAME. Used when mode is "A shop's listings". Listings are matched on the shop's own Etsy id, so listings from other shops that merely mention the name are dropped free of charge.

## `keywordSeeds` (type: `array`):

Seed terms to expand into Etsy's own ranked search suggestions, one per line. Used when mode is 'Keyword research only'. Each seed is expanded with buyer-intent modifiers and an A–Z sweep.

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

Etsy listing URLs or bare listing ids, one per line. Used when mode is 'Specific listing URLs'. Accepts any Etsy URL shape, including region-prefixed ones such as etsy.com/de/listing/123456789.

## `locale` (type: `string`):

Which Etsy storefront language and currency to read. This changes the titles, descriptions and currency you get back, and it changes which keyword suggestions Etsy returns — German shoppers and US shoppers do not search the same way. A normalised USD price is always included regardless.

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

Stop after this many listings across the whole run. This is the number you are billed for: listings that fail to resolve, listings excluded by your filters, error rows, shop summaries and coverage rows are all free.

## `expandWithKeywords` (type: `boolean`):

Turn each search term into dozens of related Etsy-ranked queries before searching. This is how you get past a single query's natural result ceiling of roughly 100 listings — leave it off for a quick sample, turn it on to sweep a whole niche. The keywords found are returned as rows too.

## `maxListingsPerTerm` (type: `integer`):

How many listings to take from a single search term before moving to the next. Values above about 100 have little effect, because one Etsy search term runs out of distinct results around there — use 'Expand each term' for more.

## `maxKeywords` (type: `integer`):

Stop after this many keyword rows. Only applies when mode is 'Keyword research only' or 'Expand each term' is on; otherwise no keyword is ever collected or charged.

## `keywordModifiers` (type: `boolean`):

Also ask Etsy for suggestions on 'personalized X', 'custom X', 'X for men', 'X gift' and sixteen other shapes Etsy shoppers actually type. Finds the commercial long tail that a bare seed misses.

## `keywordAlphabet` (type: `boolean`):

Also ask Etsy for suggestions on the seed followed by each letter and digit — the 'alphabet soup' technique. Slower, and the single richest source of long-tail keywords.

## `keywordRecursionDepth` (type: `integer`):

Re-expand the strongest keywords found and collect their suggestions too. Each round multiplies both the depth and the time. 0 disables it.

## `includeVariations` (type: `boolean`):

Fetch each listing's variation properties — sizes, colours, personalisation fields and their values. Costs one extra request per listing and is never charged separately.

## `includeDescription` (type: `boolean`):

Keep each listing's full description text. Turn it off for a much smaller dataset when you only need prices, tags and demand signals.

## `shopSummary` (type: `boolean`):

Emit one free extra row per shop seen, aggregating the listings this run found: price range and median, total favourites, bestseller count, and the shop's most-used SEO tags. Always free.

## `minPriceUsd` (type: `integer`):

Skip listings cheaper than this, in US dollars. Skipped listings are never charged. Leave empty for no minimum.

## `maxPriceUsd` (type: `integer`):

Skip listings dearer than this, in US dollars. Skipped listings are never charged. Leave empty for no maximum.

## `onlyBestsellers` (type: `boolean`):

Keep only listings Etsy has flagged as a bestseller. Everything else is skipped free of charge.

## `excludeDigital` (type: `boolean`):

Skip digital and printable listings, keeping physical products only. Skipped listings are never charged.

## `maxCostUsd` (type: `integer`):

A hard ceiling on what this run may charge. The run stops cleanly the moment the next row would cross it, and still writes its coverage rows. Leave empty for no ceiling.

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

How many listings to resolve at once. The default is a good balance; raise it only if you are collecting tens of thousands of listings and the run is time-bound.

## Actor input object example

```json
{
  "mode": "keywords",
  "searchTerms": [
    "handmade ceramic mug",
    "personalized leather wallet"
  ],
  "shopNames": [
    "CordovanLeather"
  ],
  "keywordSeeds": [
    "personalized gift"
  ],
  "listingUrls": [
    "https://www.etsy.com/listing/4472929892"
  ],
  "locale": "en-US",
  "maxItems": 100,
  "expandWithKeywords": false,
  "maxListingsPerTerm": 100,
  "maxKeywords": 500,
  "keywordModifiers": true,
  "keywordAlphabet": true,
  "keywordRecursionDepth": 0,
  "includeVariations": false,
  "includeDescription": true,
  "shopSummary": true,
  "onlyBestsellers": false,
  "excludeDigital": false,
  "concurrency": 8
}
```

# Actor output Schema

## `listings` (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 = {
    "searchTerms": [
        "handmade ceramic mug",
        "personalized leather wallet"
    ],
    "shopNames": [
        "CordovanLeather"
    ],
    "keywordSeeds": [
        "personalized gift"
    ],
    "listingUrls": [
        "https://www.etsy.com/listing/4472929892"
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("vonsensey/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 = {
    "searchTerms": [
        "handmade ceramic mug",
        "personalized leather wallet",
    ],
    "shopNames": ["CordovanLeather"],
    "keywordSeeds": ["personalized gift"],
    "listingUrls": ["https://www.etsy.com/listing/4472929892"],
}

# Run the Actor and wait for it to finish
run = client.actor("vonsensey/etsy-keyword-research-tool").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 '{
  "searchTerms": [
    "handmade ceramic mug",
    "personalized leather wallet"
  ],
  "shopNames": [
    "CordovanLeather"
  ],
  "keywordSeeds": [
    "personalized gift"
  ],
  "listingUrls": [
    "https://www.etsy.com/listing/4472929892"
  ]
}' |
apify call vonsensey/etsy-keyword-research-tool --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,vonsensey/etsy-keyword-research-tool"
        }
    }
}
```

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/1il0lasiUVrZah3Lg/builds/pNV17gAHG07Cn47Is/openapi.json
