# Amazon Keyword Suggestions Scraper (`crawlerbros/amazon-keyword-suggestions-scraper`) Actor

Discover Amazon's search-autocomplete keyword suggestions for any seed keyword, across 23 marketplaces. Expand coverage with A-Z/0-9 suffixes and recursive re-querying of newly discovered suggestions.

- **URL**: https://apify.com/crawlerbros/amazon-keyword-suggestions-scraper.md
- **Developed by:** [Crawler Bros](https://apify.com/crawlerbros) (community)
- **Categories:** E-commerce, SEO tools, Automation
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $3.00 / 1,000 results

This Actor is paid per event and usage. You are charged both the fixed price for specific events and for Apify platform usage.
Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have.

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 Suggestions Scraper

Discover **Amazon's own search-autocomplete keyword suggestions** for any seed keyword or phrase, across 23 Amazon marketplaces. Feed it one or more seeds and it returns the exact completions Amazon's search box would suggest, in the order Amazon returns them. Expand coverage past Amazon's ~10-suggestion-per-query cap with A-Z / 0-9 / custom-suffix querying, and recursively re-query newly discovered suggestions to build out a full suggestion graph.

### What this actor does

- **Any number of seed keywords** — pass a list, get suggestions for each
- **23 marketplaces** — from `amazon.com` to `amazon.co.jp`
- **Suffix expansion** — append A-Z, 0-9, or your own custom suffixes to a seed to pull more suggestions than a single raw query returns
- **Recursive expansion** — treat each newly discovered suggestion as a fresh seed, up to 2 levels deep
- **Deduplication** — skip suggestions already seen earlier in the same run
- **Empty fields are omitted**

### Output per suggestion

- `marketplace` — `countryCode`, `domain`, `marketplaceId`, `currency`, `language`
- `prefix` — the exact query string that produced this result (may include an expansion suffix, e.g. `wireless earbuds a`)
- `suggestion` — the suggested keyword text Amazon returned
- `position` — 1-based order within that specific API response
- `suggestionType` — Amazon's own suggestion-type label when present (e.g. `KEYWORD`), or `SEED` for an echoed seed-keyword record
- `expansionDepth` — 0 for a direct query of an original seed keyword, 1/2 for recursive re-queries
- `expansionParent` — the prior suggestion that was used as the seed for this query (absent at depth 0)
- `refTag` — Amazon's own click-tracking reference tag for this suggestion (e.g. `nb_sb_ss_i_1_12`)
- `candidateSources` — where the API sourced this suggestion (e.g. `local`)
- `strategyId` — the suggestion-generation strategy Amazon used (e.g. `organic`)
- `prior` — Amazon's own numeric prior/confidence score for this suggestion, when present
- `ghost` / `help` — Amazon's own booleans marking a suggestion as placeholder ("ghost") or help text, when present
- `responseId` — Amazon's own per-request correlation id for the API call that returned this suggestion
- `shuffled` — whether Amazon randomized this response's suggestion order (when `true`, `position` is even less meaningful as a ranking signal)
- `sourceUrl` — the exact `completion.amazon.{domain}` autocomplete API URL that produced this record
- `recordType: "suggestion"`, `scrapedAt`

### Input

| Field | Type | Default | Description |
|---|---|---|---|
| `keywords` | array | – | Seed keywords/phrases to expand |
| `marketplace` | string | `US` | Which Amazon marketplace's autocomplete API to query |
| `expandWith` | string | `none` | `none` / `alphabet` / `digits` / `customSuffixes` |
| `customSuffixes` | array | – | Suffixes to append (expandWith=customSuffixes) |
| `maxDepth` | int | `0` | Recursion depth for re-querying new suggestions (0-2) |
| `maxSuggestions` | int | `50` | Hard cap on emitted records (1-2000) |
| `dedupe` | bool | `true` | Skip suggestions already emitted this run |
| `includeSeed` | bool | `false` | Also emit a record for the literal seed keyword |

#### Example: quick single-keyword lookup

```json
{
  "keywords": ["wireless earbuds"],
  "marketplace": "US",
  "maxSuggestions": 20
}
```

#### Example: full A-Z expansion for keyword research

```json
{
  "keywords": ["yoga mat"],
  "marketplace": "US",
  "expandWith": "alphabet",
  "maxSuggestions": 300
}
```

#### Example: recursive 2-level expansion, UK marketplace

```json
{
  "keywords": ["running shoes"],
  "marketplace": "GB",
  "expandWith": "alphabet",
  "maxDepth": 2,
  "maxSuggestions": 500
}
```

#### Example: custom suffixes for a niche

```json
{
  "keywords": ["phone case"],
  "customSuffixes": ["iphone 15", "samsung s24", "waterproof", "wallet"],
  "expandWith": "customSuffixes",
  "maxSuggestions": 100
}
```

### Use cases

- **SEO / PPC keyword research** — discover the exact long-tail phrases Amazon shoppers' search box completes to
- **Listing optimization** — find related phrasing to include in titles and bullet points
- **Competitive intelligence** — see what completions surface for a competitor's product category
- **Content planning** — build topic clusters from a seed niche keyword
- **International expansion** — compare suggestion coverage across marketplaces for the same seed

### FAQ

**Is this a search-volume or popularity tool?**
No. This is a *suggestion-discovery* actor. Amazon's autocomplete API returns an ordered list of completions for its own UX purposes — `position` reflects that response's order at the moment of the request, not a numeric popularity or search-volume estimate. Don't treat it as one.

**Why does the same suggestion sometimes appear from different queries?**
Amazon's autocomplete can return the same completion for multiple related prefixes (e.g. both `wireless ear` and `wireless earbuds a` might surface `wireless earbuds bluetooth`). Leave `dedupe` on (the default) to keep only the first occurrence.

**Why is `expandWith` needed if I already give a full-phrase seed?**
Amazon caps each raw autocomplete response at roughly 10 suggestions per query, no matter how you phrase the seed. Appending a letter/digit/custom suffix (`{seed} a`, `{seed} b`, …) is the standard technique to surface additional completions beyond that per-request cap.

**What does `maxDepth` actually recurse on?**
Each *newly discovered* suggestion (not already seen) can itself become a new seed keyword, which is then queried (and optionally suffix-expanded) the same way. `maxDepth=1` re-queries suggestions found from your original seeds; `maxDepth=2` goes one level further.

**Is authentication or a proxy required?**
No. The autocomplete endpoint is a public, unauthenticated JSON API and responds directly to a plain HTTP request — no browser rendering, cookies, or proxy needed.

**Which marketplaces are supported?**
23 Amazon marketplaces, from the US to Japan — see the `marketplace` dropdown for the full list.

**How fresh are the suggestions?**
Live — every run queries Amazon's autocomplete API directly at request time.

**Is this affiliated with Amazon?**
No, this is a third-party actor using Amazon's public autocomplete API.

**What happens if a run returns zero suggestions?**
The run's status message tells you why. If every request to Amazon's autocomplete API failed outright (repeated network/5xx errors, even after retries) — which happens occasionally for specific marketplaces during a temporary outage on Amazon's side — the message says so explicitly and suggests retrying later or trying a different marketplace. If the requests succeeded but genuinely returned no completions (e.g. an obscure or misspelled seed keyword), you'll instead see a message suggesting a shorter, more common keyword.

### More Amazon Actors

Part of a full Amazon scraper suite — also check out:

- [Amazon Category Scraper](https://apify.com/crawlerbros/amazon-scraper)
- [Amazon Product Scraper](https://apify.com/crawlerbros/amazon-product-scraper)
- [Amazon Best Sellers & Rankings Scraper](https://apify.com/crawlerbros/amazon-bestseller-scraper)
- [Amazon Reviews Scraper](https://apify.com/crawlerbros/amazon-reviews-scraper)
- [Amazon Reviews Scraper Pro](https://apify.com/crawlerbros/amazon-reviews-scraper-pro)
- [Amazon Offers Scraper (All Offers Display)](https://apify.com/crawlerbros/amazon-offers-scraper)
- [Amazon Seller & Shop Scraper](https://apify.com/crawlerbros/amazon-seller-shop-scraper)
- [Amazon Deals Scraper](https://apify.com/crawlerbros/amazon-deals-scraper)
- [Amazon Brand Store Scraper](https://apify.com/crawlerbros/amazon-brand-store-scraper)
- [Amazon Creator Shop Scraper](https://apify.com/crawlerbros/amazon-creator-shop-scraper)
- [Amazon Wishlist & Registry Scraper](https://apify.com/crawlerbros/amazon-list-registry-scraper)

# Actor input Schema

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

One or more seed keywords/phrases to expand into Amazon autocomplete suggestions.

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

Which Amazon marketplace's autocomplete API to query.

## `expandWith` (type: `string`):

Harvest more suggestions per keyword by re-querying with an appended suffix (Amazon caps each raw response at ~10 suggestions).

## `customSuffixes` (type: `array`):

Suffixes to append to each keyword, e.g. `for men`, `waterproof`, `cheap`. Only used when expandWith is `customSuffixes`.

## `maxDepth` (type: `integer`):

Recursively re-query newly discovered suggestions as fresh seeds, up to this many levels deep (0 = only query the original seed keywords).

## `maxSuggestions` (type: `integer`):

Hard cap on total suggestion records emitted in this run.

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

Skip a suggestion value if it was already emitted earlier in this run (recommended -- expansion and recursion frequently rediscover the same suggestion).

## `includeSeed` (type: `boolean`):

Also emit one record per seed keyword itself (suggestionType `SEED`), in addition to Amazon's suggestions.

## Actor input object example

```json
{
  "keywords": [
    "wireless earbuds"
  ],
  "marketplace": "US",
  "expandWith": "none",
  "customSuffixes": [],
  "maxDepth": 0,
  "maxSuggestions": 50,
  "dedupe": true,
  "includeSeed": false
}
```

# Actor output Schema

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

Dataset containing all scraped Amazon keyword suggestions.

# 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": [
        "wireless earbuds"
    ],
    "marketplace": "US",
    "expandWith": "none",
    "customSuffixes": [],
    "maxDepth": 0,
    "maxSuggestions": 50,
    "dedupe": true,
    "includeSeed": false
};

// Run the Actor and wait for it to finish
const run = await client.actor("crawlerbros/amazon-keyword-suggestions-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": ["wireless earbuds"],
    "marketplace": "US",
    "expandWith": "none",
    "customSuffixes": [],
    "maxDepth": 0,
    "maxSuggestions": 50,
    "dedupe": True,
    "includeSeed": False,
}

# Run the Actor and wait for it to finish
run = client.actor("crawlerbros/amazon-keyword-suggestions-scraper").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": [
    "wireless earbuds"
  ],
  "marketplace": "US",
  "expandWith": "none",
  "customSuffixes": [],
  "maxDepth": 0,
  "maxSuggestions": 50,
  "dedupe": true,
  "includeSeed": false
}' |
apify call crawlerbros/amazon-keyword-suggestions-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "command": "npx",
            "args": [
                "mcp-remote",
                "https://mcp.apify.com/?tools=crawlerbros/amazon-keyword-suggestions-scraper",
                "--header",
                "Authorization: Bearer <YOUR_API_TOKEN>"
            ]
        }
    }
}

```

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/easPMPJFvogKkKuC4/builds/XalQNKF63r3IqE285/openapi.json