# Amazon Autocomplete Keyword Expander (`vexaloom-labs/amazon-autocomplete-keyword-expander`) Actor

Turn seed keywords into Amazon's own search-box autocomplete suggestions across 23 marketplaces. Expand past the usual per-query cap with A-Z/0-9/custom suffixes and recursive re-querying of newly found suggestions.

- **URL**: https://apify.com/vexaloom-labs/amazon-autocomplete-keyword-expander.md
- **Developed by:** [vexaloom-labs](https://apify.com/vexaloom-labs) (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 $0.49 / 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/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

## Amazon Autocomplete Keyword Expander

Turn a handful of seed phrases into the real keyword ideas Amazon's own search box suggests. This actor reads Amazon's public autocomplete service across **23 marketplaces**, can sweep several departments in one run, and expands each seed through eight different query axes so you see far more than the ten suggestions a single lookup returns. No account, cookies, or proxy setup is required.

### What this actor does

- **23 Amazon marketplaces** — from `amazon.com` and `amazon.co.uk` to `amazon.co.jp`, `amazon.com.au` and `amazon.in`
- **Multi-market and multi-department runs** — compare the same seed across countries and browse aliases such as electronics, kitchen, fashion or books
- **Eight expansion axes** — suffix A-Z, prefix A-Z, 0-9, questions, comparisons, prepositions, buyer modifiers and your own custom suffixes
- **Recursive discovery** — optionally treat newly found suggestions as fresh seeds, up to three hops deep
- **Two response dialects** — enhanced (thumbnails, widget cards, predictive text) or organic keyword responses, or both in one pass
- **Filters and ranking** — keep questions or long-tail phrases, require or exclude terms, cap results per seed and overall, and order by source, alphabet or the relative volume proxy
- **Deduplication with provenance** — one row per unique phrase per seed, marketplace and department, showing every query variant that surfaced it
- **Empty fields are omitted**

### Output per suggestion

- `marketplace` — `countryCode`, `domain`, `marketplaceId`, `currency`, `language`
- `seedKeyword` — the original seed this row belongs to
- `query` / `prefix` — the exact query text sent to Amazon
- `suggestion` — the suggested keyword
- `department` — the Amazon department alias used
- `locale` — the marketplace language, e.g. `en-US`
- `suggestionType` — Amazon's response type, e.g. `KEYWORD` or `WIDGET`; `SEED` for an echoed seed
- `suggType` — Amazon's finer subtype, e.g. `KeywordSuggestion`
- `expansionType` / `expansionToken` — `seed`, `suffixAlphabet`, `prefixAlphabet`, `digits`, `question`, `comparison`, `preposition`, `buyerModifier`, `custom` or `recursive`, plus the letter, digit or word used
- `expansionDepth` / `expansionParent` — recursion level and the suggestion that led to this query
- `position` / `amazonRank` — 1-based slot in the response that returned the phrase
- `bestRank` / `rank` — best slot across all queries, and final rank inside the seed group
- `volumeProxy` — how many distinct query variants surfaced the phrase; a relative signal, not monthly search volume
- `surfacedByQueries` — up to 20 query variants that returned it
- `searchUrl` — ready-to-open Amazon search URL for the suggestion
- `wordCount`, `isQuestion`, `containsSeed` — shape helpers for filtering and analysis
- `thumbnailUrl` — product thumbnail when the enhanced response supplies one
- `widget` — optional widget object: `id`, `template`, `slot`, `byline`, `refinement`, `title`, `subtitle`, `imageUrl`, `imageShape`, `linkUrl`, `items[]`
- `predictiveText` — Amazon's predictive completion for the query, when present
- `strategyId` / `strategyApiType` / `candidateSources` / `refTag` / `prior` / `ghost` / `help` — Amazon's own suggestion metadata
- `responseId` / `shuffled` — request correlation id and whether Amazon randomized the response order
- `sourceUrl` — the exact autocomplete request URL
- `recordType: "suggestion"`, `scrapedAt`

### Input

| Field | Type | Default | Description |
|---|---|---|---|
| `keywords` | array | – | Seed keywords or phrases to expand (required) |
| `marketplace` | string | `US` | Single marketplace; used when `marketplaces` is empty |
| `marketplaces` | array | `[]` | Optional codes for a multi-market sweep, e.g. `["US","GB","DE"]` |
| `departments` | array | `[]` | Department aliases, e.g. `["aps","kitchen","electronics"]` |
| `expandAlphabet` | bool | `false` | Append A-Z to each query |
| `expandPrefixAlphabet` | bool | `false` | Prepend A-Z to each query |
| `expandNumbers` | bool | `false` | Append 0-9 to each query |
| `expandQuestions` | bool | `false` | Add locale-aware question stems |
| `expandComparisons` | bool | `false` | Add `vs` / `or` / `versus` / `and` style tokens |
| `expandPrepositions` | bool | `false` | Add `for` / `with` / `without` / `under` style tokens |
| `expandBuyerModifiers` | bool | `false` | Add `best` / `cheap` / `for men` style modifiers |
| `customSuffixes` | array | `[]` | Your own suffixes |
| `maxDepth` | int | `0` | Recursion depth, 0-3 |
| `queryMode` | string | `enhanced` | `enhanced` / `organic` / `both` |
| `includeWidgets` | bool | `false` | Emit widget rows when available |
| `includeSeed` | bool | `false` | Emit one `SEED` row per seed |
| `dedupe` | bool | `true` | Merge repeats and add volume/provenance fields |
| `resultOrder` | string | `source` | `source` / `alphabetical` / `volume` |
| `mustContainSeed` | bool | `false` | Drop suggestions without the seed text |
| `includeTerms` | array | `[]` | Keep suggestions containing at least one term |
| `excludeTerms` | array | `[]` | Drop suggestions containing any term |
| `onlyQuestions` | bool | `false` | Keep question-shaped suggestions |
| `onlyLongTail` | bool | `false` | Keep suggestions with 3+ words |
| `minWordCount` | int | `0` | Drop shorter suggestions |
| `maxSuggestions` | int | `500` | Overall record cap (1-10,000) |
| `maxSuggestionsPerKeyword` | int | `0` | Per seed/market/department cap; 0 = no cap |
| `maxQueries` | int | `400` | Overall request cap (1-20,000) |
| `maxConcurrency` | int | `4` | Parallel requests (1-10) |
| `requestDelayMs` | int | `100` | Pause between requests (0-5,000 ms) |

#### Example: one seed, one market

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

#### Example: full keyword-research sweep

```json
{
  "keywords": ["yoga mat"],
  "marketplace": "US",
  "expandAlphabet": true,
  "expandPrefixAlphabet": true,
  "expandQuestions": true,
  "expandComparisons": true,
  "expandPrepositions": true,
  "expandBuyerModifiers": true,
  "maxSuggestions": 800,
  "maxQueries": 400,
  "resultOrder": "volume"
}
```

#### Example: compare countries and departments

```json
{
  "keywords": ["running shoes"],
  "marketplaces": ["US", "GB", "DE", "JP"],
  "departments": ["aps", "shoes", "fashion"],
  "maxSuggestionsPerKeyword": 150,
  "maxSuggestions": 1200
}
```

#### Example: questions and long-tail only, with thumbnails

```json
{
  "keywords": ["air purifier"],
  "marketplace": "US",
  "expandQuestions": true,
  "onlyQuestions": true,
  "onlyLongTail": true,
  "queryMode": "both",
  "includeWidgets": true,
  "maxSuggestions": 200
}
```

### Use cases

- **Amazon SEO and PPC** — build exact-match keyword lists from the phrases shoppers actually type into Amazon
- **Listing optimization** — find long-tail phrasing for titles, bullets and backend search terms
- **Niche research** — expand one product idea into hundreds of related buying-intent phrases
- **International expansion** — compare autocomplete demand signals for the same seed in different marketplaces
- **Category discovery** — sweep departments to see how suggestions change between broad and scoped searches
- **Content planning** — turn question and comparison suggestions into buying guides and FAQ content

### FAQ

#### Is this a search-volume tool?

No. Amazon does not publish monthly search volume, and this actor does not invent one. `position` is the order Amazon returned at request time, and `volumeProxy` counts how many distinct query variants surfaced the same phrase. Both are relative signals for prioritisation, not absolute demand numbers.

#### Why do I only get about ten suggestions per query?

Amazon's autocomplete response is capped at roughly ten keyword suggestions per request. The expansion axes work around that cap by sending related queries (`yoga mat a`, `a yoga mat`, `best yoga mat`, and so on), then merging and deduplicating the results.

#### What is the difference between organic and enhanced?

The organic dialect returns the plain keyword list. The enhanced dialect returns that list plus optional thumbnails, widget cards and predictive text when Amazon provides them. **Both** requests each dialect and unions the results, which costs twice as many requests but can surface extra phrases.

#### Why are thumbnails missing for some rows or markets?

Thumbnails come from Amazon's enhanced responses and are mostly present on the US and sometimes Canada marketplaces. Other markets usually return none. The field is omitted when Amazon does not supply an image; no placeholder or synthetic image is ever added.

#### How does the India marketplace work?

Amazon's own India completion host is occasionally unavailable. When that happens, the actor automatically retries the same Indian marketplace through Amazon's UK and UAE completion hosts, keeping the Indian marketplace id and locale. The run status message tells you which host was used.

#### Why did my run stop before the result count I expected?

Amazon caps each raw response, and the actor also enforces your `maxSuggestions`, `maxSuggestionsPerKeyword`, `maxQueries` and `maxDepth` limits. The run status message names the limit that stopped it, so you can raise that specific cap and run again.

#### Why do some department aliases return unrelated suggestions?

Amazon sometimes returns a generic cross-department fallback instead of an empty list. The record keeps the department alias that produced it, so you can see exactly which scope returned the phrase.

#### Is authentication, a proxy or a browser required?

No. The autocomplete service is public JSON. The actor calls it directly with no login, cookies, API key, browser rendering or proxy configuration.

#### Is this affiliated with Amazon?

No. This is an independent third-party actor that reads Amazon's public autocomplete responses.

### Limitations

- Amazon returns at most about ten keyword suggestions per query, so breadth comes from the expansion axes and the query cap.
- Thumbnails and widget rows are only available from enhanced responses and are sparse outside the US marketplace.
- `volumeProxy` is a count of distinct query variants, not search volume.
- Department scoping is Amazon's own behaviour; an unrelated alias can return a generic fallback row.
- Recursion and many expansion axes multiply request counts. Use `maxQueries`, `maxSuggestions` and `maxSuggestionsPerKeyword` to keep runs bounded.

# Actor input Schema

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

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

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

Single Amazon marketplace to query. Used when `marketplaces` is empty.

## `marketplaces` (type: `array`):

Optional multi-market sweep, e.g. \["US", "GB", "DE"]. Leave empty to use the single `marketplace` value. Codes are the same as the marketplace dropdown.

## `departments` (type: `array`):

Amazon department aliases to scope suggestions, e.g. \["aps", "kitchen"]. Leave empty for the all-departments default (`aps`). Common aliases: aps, electronics, computers, fashion, kitchen, stripbooks, beauty, hpc, pet-supplies, toys-and-games, home-improvement, automotive, grocery, office-products, watches, shoes, luggage, digital-text, audible, amazon-devices, instant-video, todays-deals.

## `expandAlphabet` (type: `boolean`):

Append each letter a-z to every query (e.g. `yoga mat a`) to surface more than the per-query cap.

## `expandPrefixAlphabet` (type: `boolean`):

Prepend each letter a-z to every query (e.g. `a yoga mat`). Returns a different suggestion set from suffix expansion.

## `expandNumbers` (type: `boolean`):

Append each digit 0-9 to every query, useful for sizes, models and quantities.

## `expandQuestions` (type: `boolean`):

Query locale-aware question stems such as `how to`, `what is` and `where to buy` in front of each seed.

## `expandComparisons` (type: `boolean`):

Query comparison tokens such as `vs`, `or`, `versus` and `and` after each seed.

## `expandPrepositions` (type: `boolean`):

Query preposition tokens such as `for`, `with`, `without`, `under` and `over` after each seed.

## `expandBuyerModifiers` (type: `boolean`):

Query locale-aware buyer-intent modifiers such as `best`, `cheap`, `for men`, `for women` and `waterproof`.

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

Additional suffixes to append to every query, e.g. \["for men", "waterproof", "iphone 15"].

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

Recursively re-query newly discovered suggestions as fresh seeds, up to this depth (0 = original seeds only; 3 = three hops).

## `queryMode` (type: `string`):

`enhanced` returns thumbnails, widgets and predictive text when Amazon provides them; `organic` is the plain keyword response; `both` requests both and unions the results.

## `includeWidgets` (type: `boolean`):

Emit Amazon's optional widget suggestions (carousels, refinements, entity cards) when the enhanced endpoint returns them.

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

Emit one `SEED` record per seed keyword in addition to Amazon's suggestions.

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

Merge repeated suggestions into one record per seed, marketplace and department, with a relative volume proxy and provenance. Turn off to emit every occurrence.

## `resultOrder` (type: `string`):

Order within each seed, marketplace and department group. `volume` sorts by the relative query-count score (requires dedupe).

## `mustContainSeed` (type: `boolean`):

Drop suggestions that do not contain the original seed keyword.

## `includeTerms` (type: `array`):

Keep only suggestions containing at least one of these terms. Leave empty to keep all.

## `excludeTerms` (type: `array`):

Drop suggestions containing any of these terms.

## `onlyQuestions` (type: `boolean`):

Keep only question-shaped suggestions (question word or trailing question mark).

## `onlyLongTail` (type: `boolean`):

Keep only suggestions with three or more words.

## `minWordCount` (type: `integer`):

Drop suggestions with fewer words than this value.

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

Hard cap on total records emitted in this run.

## `maxSuggestionsPerKeyword` (type: `integer`):

Cap emitted records per seed, marketplace and department. 0 means no per-seed cap.

## `maxQueries` (type: `integer`):

Hard cap on HTTP requests across the whole run. The run status message says when this cap stopped it.

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

Parallel requests. Values above 8 give little extra speed and are more likely to be rate-limited.

## `requestDelayMs` (type: `integer`):

Pause per worker between requests. 0 is fastest; 100-250 is gentler.

## Actor input object example

```json
{
  "keywords": [
    "wireless earbuds"
  ],
  "marketplace": "US",
  "marketplaces": [],
  "departments": [
    "aps"
  ],
  "expandAlphabet": false,
  "expandPrefixAlphabet": false,
  "expandNumbers": false,
  "expandQuestions": false,
  "expandComparisons": false,
  "expandPrepositions": false,
  "expandBuyerModifiers": false,
  "customSuffixes": [],
  "maxDepth": 0,
  "queryMode": "enhanced",
  "includeWidgets": false,
  "includeSeed": false,
  "dedupe": true,
  "resultOrder": "source",
  "mustContainSeed": false,
  "includeTerms": [],
  "excludeTerms": [],
  "onlyQuestions": false,
  "onlyLongTail": false,
  "minWordCount": 0,
  "maxSuggestions": 3,
  "maxSuggestionsPerKeyword": 0,
  "maxQueries": 3,
  "maxConcurrency": 1,
  "requestDelayMs": 100
}
```

# 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",
    "marketplaces": [],
    "departments": [
        "aps"
    ],
    "expandAlphabet": false,
    "expandPrefixAlphabet": false,
    "expandNumbers": false,
    "expandQuestions": false,
    "expandComparisons": false,
    "expandPrepositions": false,
    "expandBuyerModifiers": false,
    "customSuffixes": [],
    "maxDepth": 0,
    "queryMode": "enhanced",
    "includeWidgets": false,
    "includeSeed": false,
    "dedupe": true,
    "resultOrder": "source",
    "mustContainSeed": false,
    "includeTerms": [],
    "excludeTerms": [],
    "onlyQuestions": false,
    "onlyLongTail": false,
    "minWordCount": 0,
    "maxSuggestions": 3,
    "maxSuggestionsPerKeyword": 0,
    "maxQueries": 3,
    "maxConcurrency": 1,
    "requestDelayMs": 0
};

// Run the Actor and wait for it to finish
const run = await client.actor("vexaloom-labs/amazon-autocomplete-keyword-expander").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",
    "marketplaces": [],
    "departments": ["aps"],
    "expandAlphabet": False,
    "expandPrefixAlphabet": False,
    "expandNumbers": False,
    "expandQuestions": False,
    "expandComparisons": False,
    "expandPrepositions": False,
    "expandBuyerModifiers": False,
    "customSuffixes": [],
    "maxDepth": 0,
    "queryMode": "enhanced",
    "includeWidgets": False,
    "includeSeed": False,
    "dedupe": True,
    "resultOrder": "source",
    "mustContainSeed": False,
    "includeTerms": [],
    "excludeTerms": [],
    "onlyQuestions": False,
    "onlyLongTail": False,
    "minWordCount": 0,
    "maxSuggestions": 3,
    "maxSuggestionsPerKeyword": 0,
    "maxQueries": 3,
    "maxConcurrency": 1,
    "requestDelayMs": 0,
}

# Run the Actor and wait for it to finish
run = client.actor("vexaloom-labs/amazon-autocomplete-keyword-expander").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "keywords": [
    "wireless earbuds"
  ],
  "marketplace": "US",
  "marketplaces": [],
  "departments": [
    "aps"
  ],
  "expandAlphabet": false,
  "expandPrefixAlphabet": false,
  "expandNumbers": false,
  "expandQuestions": false,
  "expandComparisons": false,
  "expandPrepositions": false,
  "expandBuyerModifiers": false,
  "customSuffixes": [],
  "maxDepth": 0,
  "queryMode": "enhanced",
  "includeWidgets": false,
  "includeSeed": false,
  "dedupe": true,
  "resultOrder": "source",
  "mustContainSeed": false,
  "includeTerms": [],
  "excludeTerms": [],
  "onlyQuestions": false,
  "onlyLongTail": false,
  "minWordCount": 0,
  "maxSuggestions": 3,
  "maxSuggestionsPerKeyword": 0,
  "maxQueries": 3,
  "maxConcurrency": 1,
  "requestDelayMs": 0
}' |
apify call vexaloom-labs/amazon-autocomplete-keyword-expander --silent --output-dataset

```

## MCP server setup

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

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/zgFNSzKiYNCzNrdL9/builds/Lh0Nho79lKMarONeP/openapi.json