# Amazon Search Suggestions Scraper (`cyprusapi/amazon-search-suggestions`) Actor

Harvests Amazon autocomplete keyword suggestions across 18 marketplaces via the native suggestions endpoint — no browser, sub-second per keyword. Batch seeds, alphabet/0-9 and buyer-modifier expansion, deduped output with source tracking.

- **URL**: https://apify.com/cyprusapi/amazon-search-suggestions.md
- **Developed by:** [Torchtechnology LTD](https://apify.com/cyprusapi) (community)
- **Categories:** E-commerce, SEO tools, Developer tools
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

$0.02 / 1,000 suggestions

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

### What does this Actor do?

Amazon Search Suggestions Scraper harvests **Amazon's native autocomplete suggestions** — the exact phrases shoppers see in the search box — across **18 verified marketplaces**. No browser involved: the Actor talks to Amazon's own suggestions endpoint over HTTP with TLS impersonation, which makes it **sub-second per keyword** and extremely cheap to run. Batch unlimited seed keywords, expand them with alphabet/digit suffixes or buyer modifiers, and get a deduplicated keyword list with source tracking.

### Why this Actor?

- **Real shopper language** — autocomplete reflects what people actually type, in the marketplace's native language.
- **Batch + expansion built in** — one seed with `alphabet` expansion becomes up to 37 calls and hundreds of long-tail keywords; every item records which expansions surfaced it (`matchedBy`) and its best rank.
- **You pay per unique suggestion** — deduplication happens *before* charging; failed calls are never charged.
- **Fast** — no browser: a 100-keyword run finishes in seconds to minutes, not tens of minutes.

### Quick start

```json
{
  "prefixes": ["usb c cable", "yoga mat"],
  "marketplace": "com",
  "expansion": "alphabet"
}
```

Single seed without the array: `{"query": "laptop", "marketplace": "com"}`.

### Input reference

| Field | Type | Default | Description |
|---|---|---|---|
| `prefixes` | string\[] | — | Seed keywords (batch freely) |
| `query` | string | — | Single-seed convenience field |
| `marketplace` | string | `com` | One of 18: de, com, co.uk, fr, it, es, ca, com.au, co.jp, in, nl, se, pl, be, mx, br, ae, sa |
| `expansion` | string | `none` | `none` · `alphabet` (a–z, 0–9 suffixes) · `modifiers` (buyer modifiers like "for", "best", "kids") · `alphabet+modifiers` |
| `proxyConfiguration` | object | Apify Residential | Proxy settings; custom `proxyUrls` supported |
| `proxiesByMarketplace` | object | — | Geo-pinned proxies per marketplace — tried first, ahead of the bundled pool and the Apify tiers |
| `apifyProxyFallback` | boolean | `true` | After the own pool, also try Apify datacenter then Apify residential (geo-targeted) on bot-detection/transport failures |

### Output

One dataset item per **unique** suggestion:

```json
{
  "seed": "usb c cable",
  "suggestion": "usb c cable 2m",
  "rank": 1,
  "matchedBy": ["seed", "expand:2"],
  "variantCount": 2,
  "marketplace": "com",
  "scrapedAt": "2026-08-17T09:00:00Z"
}
```

| Field | Meaning |
|---|---|
| `seed` | Your input keyword |
| `suggestion` | The autocomplete phrase, verbatim |
| `rank` | Best (lowest) position seen across the calls that surfaced it |
| `matchedBy` | Which calls produced it — `seed`, `expand:x`, or `modifier:x` — measures suggestion coverage breadth |
| `variantCount` | Number of entries in `matchedBy` — how many distinct calls surfaced it (popularity proxy) |
| `marketplace`, `scrapedAt` | Provenance |

`RUN_SUMMARY` (key-value store) reports unique counts and any failed calls per run — failures are visible, never billed.

### Pricing

Pay per **unique suggestion** (`suggestion` event). Alphabet expansion of one seed ≈ 37 calls ≈ typically 150–300 unique suggestions. See the Pricing tab for the current price.

### Use with AI agents (MCP)

Actor identity: `cyprusapi/amazon-search-suggestions`. Tool description: get Amazon autocomplete keyword suggestions for seed terms across 18 marketplaces, with optional alphabet/modifier expansion, deduplicated with source tracking.

> Example prompt: "Give me Amazon.com long-tail keywords for 'yoga mat' with alphabet expansion." → input: `{"query": "yoga mat", "marketplace": "com", "expansion": "alphabet"}`

Pairs naturally with **cyprusapi/amazon-search** (check which products rank for your harvested keywords) and **cyprusapi/amazon-bestsellers** (validate demand in the category).

### FAQ & limitations

- Amazon returns up to ~10–11 suggestions per call — that's the platform's own limit; expansion modes exist to go deeper.
- Suggestions are marketplace-language native (jp → Japanese, etc.).
- Occasional empty responses for nonsense seeds are normal, not errors.
- **Proxy tier chain per call:** your `proxiesByMarketplace` pool first, then the bundled pool (per-Actor named KVS `proxy-pool-amazon-search-suggestions`, record `pool` — works under LIMITED\_PERMISSIONS; the user input always wins), then — with `apifyProxyFallback` on — Apify datacenter, then Apify residential. Retries only on bot detection/transport.
- **Legality:** the endpoint is public and powers amazon's own search box; comply with Amazon's ToS and applicable law.
- Issues tab is open — marketplace/selector maintenance is part of the product.

# Actor input Schema

## `prefixes` (type: `array`):

Seed keywords/phrases to get autocomplete suggestions for. Batch as many as you like — they share startup cost.

## `query` (type: `string`):

Convenience field for one seed — used when 'prefixes' is empty.

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

Amazon marketplace whose suggestions to query (native language per marketplace).

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

none = just the seeds · alphabet = seeds + ' a'…' z', ' 0'…' 9' (37 calls per seed) · modifiers = seeds + common buyer modifiers (for, best, cheap, with, kids, men, women, …). Expanded suggestions are deduplicated; each item records which expansions surfaced it.

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

Optional Amazon search alias to scope suggestions to a department (e.g. 'beauty', 'electronics', 'fashion', 'toys', 'kitchen', 'sports', 'automotive', 'grocery', 'books'). Empty = 'aps' (all departments).

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

The endpoint is lenient, but residential proxies are recommended for volume. Custom proxies via proxyUrls.

## `proxiesByMarketplace` (type: `object`):

Optional: {"de": \["http://user:pass@host:port", …], "co.uk": \[…]}. Geo-pinned proxies per marketplace — exit-IP country should match the marketplace, otherwise Amazon serves wrong currencies or bot-gates. Proxy tier chain per task: this explicit pool FIRST; otherwise the bundled shared pool (we cover it); on blocked/transport the run falls back to Apify datacenter, then Apify residential. With useApifyProxy off and no pool at all: single direct attempt.

## `apifyProxyFallback` (type: `boolean`):

After the own pool, also try Apify datacenter then Apify residential (geo-targeted to the marketplace) on bot-detection/transport failures. Off = no Apify tiers (own pool or single direct attempt).

## Actor input object example

```json
{
  "prefixes": [
    "usb c cable",
    "yoga mat"
  ],
  "marketplace": "com",
  "expansion": "none",
  "proxyConfiguration": {
    "useApifyProxy": true,
    "apifyProxyGroups": [
      "RESIDENTIAL"
    ]
  },
  "apifyProxyFallback": true
}
```

# Actor output Schema

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

No description

# 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 = {
    "prefixes": [
        "usb c cable",
        "yoga mat"
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("cyprusapi/amazon-search-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 = { "prefixes": [
        "usb c cable",
        "yoga mat",
    ] }

# Run the Actor and wait for it to finish
run = client.actor("cyprusapi/amazon-search-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 '{
  "prefixes": [
    "usb c cable",
    "yoga mat"
  ]
}' |
apify call cyprusapi/amazon-search-suggestions --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,cyprusapi/amazon-search-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/VdAb8bYL7na6ugEv8/builds/BU6MyXhb78oyTYP3Y/openapi.json