# Etsy Keyword Evidence Research Tool (`khadinakbar/etsy-keyword-research-tool`) Actor

Discover Etsy keyword ideas from public indexed listing evidence. Returns deduplicated phrases, confidence, transparent opportunity scores, source queries, and canonical evidence URLs for listing-title and market research.

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

## Pricing

from $4.00 / 1,000 evidence-backed keywords

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/platform/actors/running/actors-in-store#pay-per-event

## What's an Apify Actor?

Actors are a software tools running on the Apify platform, for all kinds of web data extraction and automation use cases.
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.

In JavaScript/TypeScript projects, use official [JavaScript/TypeScript client](https://docs.apify.com/api/client/js/docs.md):

```bash
npm install apify-client
```

In Python projects, use official [Python client library](https://docs.apify.com/api/client/python/docs.md):

```bash
pip install apify-client
```

In shell scripts, use [Apify CLI](https://docs.apify.com/cli/docs.md):

````bash
# MacOS / Linux
curl -fsSL https://apify.com/install-cli.sh | bash
# Windows
irm https://apify.com/install-cli.ps1 | iex
```bash

In AI frameworks, you might use the [Apify MCP server](https://docs.apify.com/integrations/mcp.md).

If your project is in a different language, use 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 with Reproducible Listing Evidence

Turn Etsy niche or product seed phrases into a structured shortlist of keyword ideas supported by public indexed listing evidence. Each dataset row represents one deduplicated phrase with the related seeds, distinct listing evidence, source queries, canonical Etsy URLs, confidence, and a transparent opportunity score for listing-title and market research.

### Best fit for this Actor

Choose this Actor when your workflow starts with product or niche phrases and needs explainable Etsy keyword ideas. To continue from research into live listing discovery, send a returned `keyword` to the [Etsy Product Search Scraper](https://apify.com/khadinakbar/etsy-product-search-scraper) as its `searchQuery`, then analyze the resulting listing URLs, titles, prices, shops, and reviews.

### A practical listing-research scenario

An Etsy seller starts with a product concept such as `ceramic mug`. The Actor expands that seed through public indexed listing evidence, ranks deduplicated phrases, and returns the supporting listing URLs and source queries. The seller then reviews the evidence and continues with selected phrases in a listing-search or merchandising workflow.

### Quick start input

```json
{
  "seedKeywords": ["ceramic mug"],
  "maxKeywords": 20,
  "maxSearchesPerSeed": 4,
  "expansionCharacters": "abcd",
  "countryCode": "US"
}
````

`maxKeywords` controls the maximum number of saved keyword records, while `maxSearchesPerSeed` and `expansionCharacters` shape the breadth of the public-index evidence pass.

### What data you receive

| Field | Meaning |
| --- | --- |
| `keyword` | Candidate phrase extracted from indexed Etsy listing titles |
| `seedKeywords` | Input seeds connected to the phrase |
| `evidenceCount` | Distinct canonical listing URLs supporting the phrase |
| `opportunityScore` | Transparent ordering score based on evidence and phrase specificity |
| `confidence` | Qualitative evidence band |
| `sourceType` | Public indexed Etsy listing evidence |
| `evidenceUrls` | Canonical Etsy listing URLs for review |
| `sourceQueries` | Public-index searches that surfaced the evidence |
| `collectedAt`, `searchUrl` | Collection context and a continued Etsy search route |

```json
{
  "keyword": "ceramic coffee mug",
  "seedKeywords": ["ceramic mug"],
  "evidenceCount": 2,
  "opportunityScore": 81,
  "confidence": "medium",
  "sourceType": "public_indexed_etsy_listing",
  "evidenceUrls": [
    "https://www.etsy.com/listing/1234567890/ceramic-coffee-mug"
  ],
  "sourceQueries": ["ceramic mug a"],
  "collectedAt": "<ISO-8601 collection time>",
  "searchUrl": "https://www.etsy.com/search?q=ceramic%20coffee%20mug"
}
```

### Run through the Apify API

```bash
curl -X POST "https://api.apify.com/v2/acts/khadinakbar~etsy-keyword-research-tool/runs" \
  -H "Authorization: Bearer $APIFY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"seedKeywords":["ceramic mug"],"maxKeywords":20,"maxSearchesPerSeed":4,"countryCode":"US"}'
```

Read the default dataset for keyword evidence rows and retain `evidenceUrls` for source review.

### Use with AI agents through Apify MCP

Example prompt:

> Research Etsy keyword ideas for these product seeds. Return each keyword, confidence, opportunity score, distinct evidence count, source queries, canonical evidence URLs, and collection time. Read the dataset and recommend a focused shortlist with source provenance.

Give the agent clear seed phrases and a bounded keyword scope. Ask it to preserve evidence URLs, explain its shortlist using the returned fields, and report the dataset outcome and Apify cost.

### Pricing

This Actor uses Pay per event plus Apify platform usage. A keyword event is associated with an evidence-backed record saved to the dataset. Open the live Pricing tab for current billing details and use `maxKeywords` or Apify run cost controls to keep the research pass aligned with your budget.

### Best results

Provide specific product or niche phrases, use a focused country code for the public-index request route, and review `evidenceUrls` alongside each returned phrase. Continue with the Etsy Product Search Scraper when listing-level fields support the next decision.

### Builder's note

I learned that a keyword suggestion becomes much easier to trust when the record carries the exact listing URLs and source queries that produced it. I built the ranking around distinct evidence and phrase specificity so the dataset explains its ordering instead of presenting an opaque score.

### Responsible use

Collect public evidence you are authorized to access and follow applicable laws, Etsy terms, and your organization's marketplace research policies.

# Actor input Schema

## `seedKeywords` (type: `array`):

Use this when you have product or niche phrases to expand into Etsy keyword ideas. Enter 1-5 plain-text phrases, for example \["ceramic mug"] or \["wedding invitation", "bridal shower invite"]. The run searches public indexed Etsy listing evidence for each seed. This is not a list of Etsy listing URLs or a request for live Etsy search volume.

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

Use this when you need to cap output rows and Pay-per-event spend. Choose an integer from 1 to 100; for example 40. The default is 40 and records are sorted by transparent evidence score. This is not a request limit for Etsy or a guaranteed number of unique ideas.

## `maxSearchesPerSeed` (type: `integer`):

Use this when you want a wider or narrower public-index evidence pass. Choose an integer from 1 to 12; for example 8, which runs the seed plus suffix variations. The default is 8 and higher values can improve variety but take longer. This is not a depth setting for crawling Etsy pages.

## `expansionCharacters` (type: `string`):

Use this when you want to control the letter or digit suffixes appended to each seed for evidence discovery. Enter characters such as "abcdefghijkl"; the default is the first twelve letters. Non-alphanumeric characters are ignored. This is not a keyword list and does not change the returned market country.

## `countryCode` (type: `string`):

Use this when public-index requests should originate from a specific two-letter country code. Enter a code such as "US" or "GB"; the default is US. It controls the proxy region and is saved as run context only. This is not a promise that Etsy results or prices are localized to that market.

## Actor input object example

```json
{
  "seedKeywords": [
    "ceramic mug"
  ],
  "maxKeywords": 40,
  "maxSearchesPerSeed": 8,
  "expansionCharacters": "abcdefghijkl",
  "countryCode": "US"
}
```

# Actor output Schema

## `keywords` (type: `string`):

Default dataset with one evidence-backed keyword record per item, including confidence, score, source queries, and canonical listing URLs.

## `output` (type: `string`):

OUTPUT key-value record with the terminal outcome, message, and key run totals.

## `runSummary` (type: `string`):

RUN\_SUMMARY key-value record with terminal outcome, result counts, upstream-query diagnostics, and cost-cap context.

# 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 = {
    "seedKeywords": [
        "ceramic mug"
    ],
    "maxKeywords": 10,
    "maxSearchesPerSeed": 2,
    "expansionCharacters": "a",
    "countryCode": "US"
};

// Run the Actor and wait for it to finish
const run = await client.actor("khadinakbar/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 = {
    "seedKeywords": ["ceramic mug"],
    "maxKeywords": 10,
    "maxSearchesPerSeed": 2,
    "expansionCharacters": "a",
    "countryCode": "US",
}

# Run the Actor and wait for it to finish
run = client.actor("khadinakbar/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 '{
  "seedKeywords": [
    "ceramic mug"
  ],
  "maxKeywords": 10,
  "maxSearchesPerSeed": 2,
  "expansionCharacters": "a",
  "countryCode": "US"
}' |
apify call khadinakbar/etsy-keyword-research-tool --silent --output-dataset

```

## MCP server setup

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

```

## OpenAPI specification

```json
{
    "openapi": "3.0.1",
    "info": {
        "title": "Etsy Keyword Evidence Research Tool",
        "description": "Discover Etsy keyword ideas from public indexed listing evidence. Returns deduplicated phrases, confidence, transparent opportunity scores, source queries, and canonical evidence URLs for listing-title and market research.",
        "version": "1.0",
        "x-build-id": "f85gQH7GEzZex6ywX"
    },
    "servers": [
        {
            "url": "https://api.apify.com/v2"
        }
    ],
    "paths": {
        "/acts/khadinakbar~etsy-keyword-research-tool/run-sync-get-dataset-items": {
            "post": {
                "operationId": "run-sync-get-dataset-items-khadinakbar-etsy-keyword-research-tool",
                "x-openai-isConsequential": false,
                "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.",
                "tags": [
                    "Run Actor"
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/inputSchema"
                            }
                        }
                    }
                },
                "parameters": [
                    {
                        "name": "token",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Enter your Apify token here"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK"
                    }
                }
            }
        },
        "/acts/khadinakbar~etsy-keyword-research-tool/runs": {
            "post": {
                "operationId": "runs-sync-khadinakbar-etsy-keyword-research-tool",
                "x-openai-isConsequential": false,
                "summary": "Executes an Actor and returns information about the initiated run in response.",
                "tags": [
                    "Run Actor"
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/inputSchema"
                            }
                        }
                    }
                },
                "parameters": [
                    {
                        "name": "token",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Enter your Apify token here"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/runsResponseSchema"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/acts/khadinakbar~etsy-keyword-research-tool/run-sync": {
            "post": {
                "operationId": "run-sync-khadinakbar-etsy-keyword-research-tool",
                "x-openai-isConsequential": false,
                "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.",
                "tags": [
                    "Run Actor"
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/inputSchema"
                            }
                        }
                    }
                },
                "parameters": [
                    {
                        "name": "token",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Enter your Apify token here"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK"
                    }
                }
            }
        }
    },
    "components": {
        "schemas": {
            "inputSchema": {
                "type": "object",
                "required": [
                    "seedKeywords"
                ],
                "properties": {
                    "seedKeywords": {
                        "title": "Seed keywords",
                        "type": "array",
                        "description": "Use this when you have product or niche phrases to expand into Etsy keyword ideas. Enter 1-5 plain-text phrases, for example [\"ceramic mug\"] or [\"wedding invitation\", \"bridal shower invite\"]. The run searches public indexed Etsy listing evidence for each seed. This is not a list of Etsy listing URLs or a request for live Etsy search volume.",
                        "items": {
                            "type": "string"
                        }
                    },
                    "maxKeywords": {
                        "title": "Maximum keyword records",
                        "type": "integer",
                        "description": "Use this when you need to cap output rows and Pay-per-event spend. Choose an integer from 1 to 100; for example 40. The default is 40 and records are sorted by transparent evidence score. This is not a request limit for Etsy or a guaranteed number of unique ideas.",
                        "default": 40
                    },
                    "maxSearchesPerSeed": {
                        "title": "Evidence searches per seed",
                        "type": "integer",
                        "description": "Use this when you want a wider or narrower public-index evidence pass. Choose an integer from 1 to 12; for example 8, which runs the seed plus suffix variations. The default is 8 and higher values can improve variety but take longer. This is not a depth setting for crawling Etsy pages.",
                        "default": 8
                    },
                    "expansionCharacters": {
                        "title": "Suffix characters",
                        "type": "string",
                        "description": "Use this when you want to control the letter or digit suffixes appended to each seed for evidence discovery. Enter characters such as \"abcdefghijkl\"; the default is the first twelve letters. Non-alphanumeric characters are ignored. This is not a keyword list and does not change the returned market country.",
                        "default": "abcdefghijkl"
                    },
                    "countryCode": {
                        "title": "Proxy country",
                        "type": "string",
                        "description": "Use this when public-index requests should originate from a specific two-letter country code. Enter a code such as \"US\" or \"GB\"; the default is US. It controls the proxy region and is saved as run context only. This is not a promise that Etsy results or prices are localized to that market.",
                        "default": "US"
                    }
                }
            },
            "runsResponseSchema": {
                "type": "object",
                "properties": {
                    "data": {
                        "type": "object",
                        "properties": {
                            "id": {
                                "type": "string"
                            },
                            "actId": {
                                "type": "string"
                            },
                            "userId": {
                                "type": "string"
                            },
                            "startedAt": {
                                "type": "string",
                                "format": "date-time",
                                "example": "2025-01-08T00:00:00.000Z"
                            },
                            "finishedAt": {
                                "type": "string",
                                "format": "date-time",
                                "example": "2025-01-08T00:00:00.000Z"
                            },
                            "status": {
                                "type": "string",
                                "example": "READY"
                            },
                            "meta": {
                                "type": "object",
                                "properties": {
                                    "origin": {
                                        "type": "string",
                                        "example": "API"
                                    },
                                    "userAgent": {
                                        "type": "string"
                                    }
                                }
                            },
                            "stats": {
                                "type": "object",
                                "properties": {
                                    "inputBodyLen": {
                                        "type": "integer",
                                        "example": 2000
                                    },
                                    "rebootCount": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "restartCount": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "resurrectCount": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "computeUnits": {
                                        "type": "integer",
                                        "example": 0
                                    }
                                }
                            },
                            "options": {
                                "type": "object",
                                "properties": {
                                    "build": {
                                        "type": "string",
                                        "example": "latest"
                                    },
                                    "timeoutSecs": {
                                        "type": "integer",
                                        "example": 300
                                    },
                                    "memoryMbytes": {
                                        "type": "integer",
                                        "example": 1024
                                    },
                                    "diskMbytes": {
                                        "type": "integer",
                                        "example": 2048
                                    }
                                }
                            },
                            "buildId": {
                                "type": "string"
                            },
                            "defaultKeyValueStoreId": {
                                "type": "string"
                            },
                            "defaultDatasetId": {
                                "type": "string"
                            },
                            "defaultRequestQueueId": {
                                "type": "string"
                            },
                            "buildNumber": {
                                "type": "string",
                                "example": "1.0.0"
                            },
                            "containerUrl": {
                                "type": "string"
                            },
                            "usage": {
                                "type": "object",
                                "properties": {
                                    "ACTOR_COMPUTE_UNITS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATASET_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATASET_WRITES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "KEY_VALUE_STORE_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "KEY_VALUE_STORE_WRITES": {
                                        "type": "integer",
                                        "example": 1
                                    },
                                    "KEY_VALUE_STORE_LISTS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "REQUEST_QUEUE_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "REQUEST_QUEUE_WRITES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATA_TRANSFER_INTERNAL_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATA_TRANSFER_EXTERNAL_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "PROXY_RESIDENTIAL_TRANSFER_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "PROXY_SERPS": {
                                        "type": "integer",
                                        "example": 0
                                    }
                                }
                            },
                            "usageTotalUsd": {
                                "type": "number",
                                "example": 0.00005
                            },
                            "usageUsd": {
                                "type": "object",
                                "properties": {
                                    "ACTOR_COMPUTE_UNITS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATASET_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATASET_WRITES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "KEY_VALUE_STORE_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "KEY_VALUE_STORE_WRITES": {
                                        "type": "number",
                                        "example": 0.00005
                                    },
                                    "KEY_VALUE_STORE_LISTS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "REQUEST_QUEUE_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "REQUEST_QUEUE_WRITES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATA_TRANSFER_INTERNAL_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATA_TRANSFER_EXTERNAL_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "PROXY_RESIDENTIAL_TRANSFER_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "PROXY_SERPS": {
                                        "type": "integer",
                                        "example": 0
                                    }
                                }
                            }
                        }
                    }
                }
            }
        }
    }
}
```