# Amazon Keyword Research Tool (`apt_marble/amazon-keyword-research`) Actor

Turn seed terms into the keywords Amazon suggests to shoppers. Expand each seed through a-z and shopping modifiers, de-duplicated across the run, and optionally attach competition data: how many products compete, the price range, how many placements are paid, and the leading brands.

- **URL**: https://apify.com/apt\_marble/amazon-keyword-research.md
- **Developed by:** [Hamza](https://apify.com/apt_marble) (community)
- **Categories:** E-commerce
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $0.40 / 1,000 keyword discovereds

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

## Amazon Keyword Research Tool

Find the search terms Amazon itself puts in front of shoppers. Give the actor a
few seed keywords and it expands each one into the terms Amazon suggests as
people type — the same drop-down every shopper sees — then optionally measures
how contested each term is by looking at the products Amazon actually returns
for it. Built for sellers writing listings, agencies planning campaigns, and
anyone who would rather work from Amazon's own suggestions than from guesswork.

### What you can do with it

- **Build a keyword list for a listing.** Expand your product term through the
  alphabet and take the long-tail phrases shoppers actually type.
- **Find low-competition entry points.** Sort by competition and look for terms
  where few paid placements and shallow result sets suggest room to rank.
- **Research a niche before you enter it.** Price ranges and the brands that
  keep appearing tell you what a category costs to compete in.
- **Plan advertising.** Every keyword comes back with how much of Amazon's first
  page of results is paid placement.
- **Discover the words shoppers use for your product.** Suggestions surface the
  phrasing and brand modifiers real buyers type, which is rarely the wording on
  the box.
- **Repeat it per marketplace.** The same seed produces a different list on each
  country's Amazon site.

### What you get

One row per discovered keyword. Without competition data, a row looks like this:

```json
{
  "keyword": "laptop stand",
  "seedKeyword": "laptop",
  "source": "suggestion",
  "depth": 1,
  "expandedFrom": "laptop",
  "suggestionRank": 3,
  "suggestionType": "KEYWORD",
  "marketplace": "us",
  "department": "aps",
  "hasCompetitionData": false,
  "scrapedAt": "2026-08-07T12:00:00.000Z"
}
```

With **Include competition data** switched on, each row also carries what Amazon
serves for that term:

```json
{
  "keyword": "laptop stand",
  "seedKeyword": "laptop",
  "suggestionRank": 3,
  "hasCompetitionData": true,
  "resultCount": 48,
  "resultPagesAvailable": 7,
  "sponsoredCount": 6,
  "organicCount": 42,
  "minPrice": 9.99,
  "maxPrice": 199.99,
  "medianPrice": 34.99,
  "currency": "USD",
  "averageRating": 4.55,
  "medianRatingsCount": 2320,
  "topBrands": ["HUANUO", "Nulaxy", "Lamicall"],
  "brandCount": 12,
  "competitionScore": 90,
  "competitionLevel": "high"
}
```

`competitionLevel` follows one published rule: how far Amazon's result set goes
for the term, how much of the first page is paid placement, how established the
products ranking for it already are, and how well they are rated. It is an
indication, not a measurement of demand.

### Input reference

| Input | Type | Default | What it does |
| --- | --- | --- | --- |
| **Seed keywords** | list of text | `wireless earbuds`, `yoga mat` | Starting terms. Each is expanded into the suggestions Amazon offers shoppers typing it. |
| **Expansion depth** | choice | `Alphabet expansion (a-z)` | `Suggestions only` asks once per seed. `Alphabet` adds a–z to every seed. `Shopping modifiers` adds words like best, cheap, for, with, near and under, both before and after the seed. `Deep` does both, then expands the best results one level further. |
| **Maximum keywords per seed** | number | `200` | Stop after this many keywords discovered from each seed. Up to 3,000. |
| **Department** | choice | `All departments` | Limit suggestions to one Amazon department, as a shopper would with the search drop-down. |
| **Include competition data** | true / false | `false` | Run a real Amazon search for every keyword and attach the competition picture. Much slower, and billed separately. |
| **Amazon marketplace** | choice | `United States` | Which country's Amazon site to read. Prices come back in that marketplace's own currency. |
| **Parallel targets** | number | `4` | How many terms to work on at the same time, up to 10. Higher is faster, but Amazon serves fewer complete results when pushed hard. |

### Output fields

| Field | Type | Description |
| --- | --- | --- |
| `keyword` | text | The discovered search term. |
| `seedKeyword` | text | The seed it came from. |
| `source` | text | `seed`, `suggestion`, `alphabet`, `modifier` or `deep` — how the term was reached. |
| `depth` | number | `0` for your own seed, `1` for its suggestions, `2` for the second level in deep mode. |
| `expandedFrom` | text | The exact term that was typed to surface it. |
| `suggestionRank` | number | The position Amazon gave the term in its own suggestion list. This is the only popularity signal Amazon publishes. |
| `suggestionType` | text | The kind of suggestion Amazon returned. |
| `marketplace` | text | The marketplace the run used. |
| `department` | text | The department the suggestions were scoped to. |
| `hasCompetitionData` | true / false | Whether the competition fields below were measured. |
| `resultCount` | number | How many products Amazon served for the term. Null when competition data was not collected. |
| `resultPagesAvailable` | number | How far Amazon's result set goes for the term. |
| `sponsoredCount` | number | How many of the served products were paid placements. |
| `organicCount` | number | How many were not. |
| `minPrice` / `maxPrice` / `medianPrice` | number | Price range across the served products. |
| `currency` | text | The currency those prices are actually in. |
| `averageRating` | number | Average star rating of the unpaid results. |
| `medianRatingsCount` | number | Middle review count of the unpaid results — how established the competition is. |
| `topBrands` | list | The brands appearing most often across the served products. |
| `brandCount` | number | How many distinct brands appeared. |
| `competitionScore` | number | 0–100, from the rule described above. |
| `competitionLevel` | text | `low`, `medium`, `high`, or `none` when Amazon served nothing. |
| `scrapedAt` | text | Collection timestamp, in UTC. |

### Pricing

You pay per result, with no monthly minimum.

| What you pay for | Price |
| --- | --- |
| Each keyword discovered | **$0.40 per 1,000** |
| Each keyword with competition data attached | **$1.50 per 1,000** extra |

**Worked example.** Two seeds with alphabet expansion typically yields around 250
keywords: **$0.10**. Switch on competition data for the same run and it is
250 × ($0.0004 + $0.0015) = **$0.48**.

Keyword discovery is deliberately cheap — it is the light half of the job.
Competition data means a real Amazon search behind every single keyword, which
is the heavy half, so it is optional, off by default, and priced on its own.

### Limits & what this actor cannot do

- **Amazon does not publish search volume for its suggestions, and this actor
  does not invent one.** There is no monthly-searches number anywhere in what
  Amazon returns. What you get instead is `suggestionRank`: the order Amazon
  itself put the terms in, which is a genuine popularity signal and the only one
  that exists. Any tool quoting an exact Amazon search volume is modelling it,
  not reading it.
- Amazon's own printed result total is not reliable — the same keyword read
  minutes apart can print wildly different totals. Competition figures here are
  built only from products Amazon actually served, and `competitionLevel` is
  described as an indication rather than a count.
- Amazon returns about ten suggestions per term typed. That ceiling is exactly
  why expansion exists: alphabet and modifier modes ask many times to build a
  large list from a small seed.
- Amazon publishes a limited number of public results for any one search, so the
  competition picture reflects the results Amazon makes available rather than an
  unlimited catalogue.
- Brands are taken from the products Amazon serves for the term, so they reflect
  who is ranking today rather than everyone selling in the category.
- Suggestions and results are a snapshot at the moment of collection and keep
  changing afterwards.
- Suggestions, prices and competition differ between Amazon marketplaces;
  results reflect the marketplace you select.
- Sponsored placements appear inside Amazon's own results; they are counted
  separately so you can see how much of a term is paid.
- Speed depends on the size of the job and on Amazon's own response times. No
  fixed throughput is promised.
- Amazon's terms govern automated access. You are responsible for using the data
  lawfully, in line with the source site's terms, and for handling any personal
  data in line with applicable privacy law.

### FAQ

**Do I need an Amazon account?**
No. The actor reads only what Amazon shows the public.

**Does it need my login or password?**
No. There is nothing to connect and nothing to sign in to — enter your seed
terms and press start.

**Can I schedule it?**
Yes. Suggestions shift with the season and with demand, so a weekly or monthly
run gives you a useful history. Every row is stamped with its collection time.

**Does it give me search volume?**
No, and neither does Amazon. Amazon publishes its suggestions in ranked order
and nothing else, so this actor reports that rank honestly instead of printing a
number that would be made up.

**How many keywords will I get from one seed?**
Alphabet expansion typically produces somewhere between 100 and 250 keywords per
seed; deep expansion produces more. Duplicates are removed across the whole run,
so you are never charged twice for the same term.

**Is the data complete?**
It is complete for what Amazon suggests: every term Amazon offered for the
prefixes that were tried, de-duplicated. It is not every keyword in existence,
because Amazon does not publish such a list.

**Why do two of my keywords have the same competition level?**
Because the level is a band, not a score out of a thousand. Use
`competitionScore`, `sponsoredCount` and `medianRatingsCount` when you need to
separate terms inside the same band.

# Actor input Schema

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

Starting terms. Each is expanded into the suggestions Amazon offers shoppers typing it.

## `expansionMode` (type: `string`):

How far to expand each seed. Alphabet adds a-z to every seed; modifiers adds common shopping words; deep does both and then expands the best results again.

## `maxKeywordsPerSeed` (type: `integer`):

Stop after this many keywords discovered from each seed.

## `categoryFilter` (type: `string`):

Limit suggestions to one Amazon department, as a shopper would with the search dropdown.

## `includeCompetition` (type: `boolean`):

Run a real Amazon search for each keyword and attach how many products compete for it, the price range and how many placements are paid. Much slower.

## `marketplace` (type: `string`):

Which country's Amazon site to read. Prices, availability and rankings differ between marketplaces, and results come back in that marketplace's own currency.

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

How many targets to work on at the same time. Higher is faster but Amazon serves fewer complete pages when pushed hard. Leave at 4 unless you have a reason.

## Actor input object example

```json
{
  "seedKeywords": [
    "wireless earbuds",
    "yoga mat"
  ],
  "expansionMode": "alphabet",
  "maxKeywordsPerSeed": 100,
  "categoryFilter": "aps",
  "includeCompetition": false,
  "marketplace": "us",
  "maxConcurrency": 4
}
```

# Actor output Schema

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

Every row this run produced.

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

What this run collected, and anything it could not read.

# 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": [
        "wireless earbuds",
        "yoga mat"
    ],
    "expansionMode": "alphabet",
    "maxKeywordsPerSeed": 100,
    "categoryFilter": "aps",
    "includeCompetition": false,
    "marketplace": "us",
    "maxConcurrency": 4
};

// Run the Actor and wait for it to finish
const run = await client.actor("apt_marble/amazon-keyword-research").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": [
        "wireless earbuds",
        "yoga mat",
    ],
    "expansionMode": "alphabet",
    "maxKeywordsPerSeed": 100,
    "categoryFilter": "aps",
    "includeCompetition": False,
    "marketplace": "us",
    "maxConcurrency": 4,
}

# Run the Actor and wait for it to finish
run = client.actor("apt_marble/amazon-keyword-research").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 '{
  "seedKeywords": [
    "wireless earbuds",
    "yoga mat"
  ],
  "expansionMode": "alphabet",
  "maxKeywordsPerSeed": 100,
  "categoryFilter": "aps",
  "includeCompetition": false,
  "marketplace": "us",
  "maxConcurrency": 4
}' |
apify call apt_marble/amazon-keyword-research --silent --output-dataset

```

## MCP server setup

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

```

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/SW5hAz5EbhoefySwT/builds/gmAtxRFdiC9c2ihvh/openapi.json