# Amazon Keyword Suggestions - Autocomplete Keyword Research (`xtracto/amazon-keyword-suggestions`) Actor

Pull Amazon's own search autocomplete suggestions for any seed keyword, expanded a-z, across 18 marketplaces. The keywords Amazon shows shoppers - what they actually type - for listing optimisation and PPC research. HTTP-only, no account.

- **URL**: https://apify.com/xtracto/amazon-keyword-suggestions.md
- **Developed by:** [Farhan Febrian Nauval](https://apify.com/xtracto) (community)
- **Categories:** E-commerce
- **Stats:** 3 total users, 2 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $1.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/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 Keyword Suggestions — Autocomplete Keyword Research

Pull Amazon's **own search autocomplete suggestions** for any seed keyword, expanded a–z, across
18 marketplaces. These are the phrases Amazon shows shoppers — what people actually type — which
is what you want for listing optimisation and PPC research. HTTP-only, no account, no API key.

### Input

| Field | Type | Default | Description |
|---|---|---|---|
| `keywords` | array | *required* | Seed terms to expand |
| `marketplace` | enum | `US` | Which Amazon site — 18 supported |
| `department` | string | `aps` | Search alias: `aps` (all), `electronics`, `kitchen`, `books`… |
| `expansion` | enum | `alphabet` | `none`, `alphabet` (a–z), `alphanumeric` (a–z, 0–9) |
| `maxKeywordsPerSeed` | integer | `500` | Stop a seed at this many unique keywords |
| `maxConcurrency` | integer | `5` | Parallel requests |

### Why the a–z expansion matters

A plain autocomplete call returns about **10** suggestions. Asking for the seed *plus each
letter* — `laptop stand a`, `laptop stand b`, … — turns that into a real keyword set:

| Seed | Probes | Unique keywords |
|---|---|---|
| `laptop stand` | 27 | **243** |
| `yoga mat` | 27 | **251** |

Keywords are deduplicated across probes (`laptop b` and `laptop ba` both surface `laptop bag`),
and each row keeps the `prefix` that produced it so you can see which probe found what.

### Output

```jsonc
{
  "_input": "laptop stand",
  "_source": "S1-completion-api",
  "_scrapedAt": "2026-09-07T06:23:20Z",

  "seed": "laptop stand",
  "prefix": "laptop stand b",       // the exact probe sent
  "keyword": "laptop stand bamboo",
  "rank": 2,                        // position within that probe's answer
  "marketplace": "US",
  "department": "aps",
  "suggestionType": "KeywordSuggestion",
  "strategyId": "organic",
  "candidateSources": "local",
  "isGhost": false,
  "refTag": "nb_sb_ss_i_1_6"
}
```

494 rows across two seeds in testing, **zero duplicates**, every field populated.

### How it works

`completion.amazon.<tld>/api/2017/suggestions` is the endpoint behind the search box.

#### Each marketplace has its own host — and the wrong one fails silently

This is the trap worth knowing. `completion.amazon.com` with a **non-US marketplace id** returns
**HTTP 200 with an empty suggestions array**. Not an error, not a redirect — just nothing. An
actor that hardcodes the `.com` host and swaps only the marketplace id therefore ships UK, DE and
JP options that quietly return no keywords, and nothing in the response says so.

Every host/id pair here was verified by asking for "laptop" and checking the answers came back in
the right language:

| Market | Returns |
|---|---|
| DE | `laptop ständer`, `laptoptasche`, `laptop 17 zoll` |
| TR | `laptop çantası` |
| MX | `laptop gamer` |
| PL | `laptop 17 cali` |

17 of 18 marketplaces answered on the first attempt. **India returned HTTP 502** during testing —
it is included, but may fail.

### Known limits

| Limit | Detail |
|---|---|
| No search volume | Amazon does not expose volume or competition here — these are suggestions, ranked, nothing more |
| ~10 per probe | The expansion is what produces breadth; there is no page parameter |
| Suggestions are personalised-ish | Ranking varies slightly by region and over time; run scheduled if you want a trend |
| India | 502 at the time of writing |

# Actor input Schema

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

Seed terms to expand, e.g. 'laptop stand'. Each seed is probed on its own and again with every letter appended.

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

Which Amazon site to ask. Each one has its own suggestion service and returns keywords in that market's language.

## `department` (type: `string`):

Amazon search alias to scope suggestions, e.g. aps (all departments), electronics, kitchen, sporting, books.

## `expansion` (type: `string`):

none = just the seed (about 10 keywords). alphabet = seed plus a-z (the usual keyword-research sweep). alphanumeric = a-z and 0-9.

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

Stop a seed once this many unique keywords have been collected.

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

Parallel requests. Each seed makes one request per letter, so this controls how fast a sweep runs.

## `proxyConfiguration` (type: `object`):

Recommended for large sweeps - an alphabet expansion is 27 requests per seed.

## Actor input object example

```json
{
  "keywords": [
    "yoga mat",
    "wireless earbuds"
  ],
  "marketplace": "US",
  "department": "aps",
  "expansion": "alphabet",
  "maxKeywordsPerSeed": 500,
  "maxConcurrency": 5,
  "proxyConfiguration": {
    "useApifyProxy": true
  }
}
```

# Actor output Schema

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

Dataset items shown in the 'Keywords' view.

## `items` (type: `string`):

Every record this run produced, with all fields, as JSON.

# 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": [
        "laptop stand"
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("xtracto/amazon-keyword-suggestions").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": ["laptop stand"] }

# Run the Actor and wait for it to finish
run = client.actor("xtracto/amazon-keyword-suggestions").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": [
    "laptop stand"
  ]
}' |
apify call xtracto/amazon-keyword-suggestions --silent --output-dataset

```

## MCP server setup

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

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/nf9ecOQ5wC70bq6FK/builds/KxqL3jbvqkxEwEWlE/openapi.json