# Amazon Keyword Search Scraper (`cyprusapi/amazon-keyword-search`) Actor

Search Amazon by keyword and get full product records back - not just titles. Organic results in Amazon's own order, no sponsored listings. Prices, sales rank, ratings, images and price statistics for every hit, across 12 marketplaces. Errors are never charged.

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

## Pricing

from $2.00 / 1,000 search results

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/actors/running/actors-in-store.md#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 Search Scraper

Type a keyword, get Amazon's own search results back as **full product
records** — in Amazon's own ranking, and **without sponsored placements**.

This is the search result page a shopper sees, minus the ads, plus everything
a shopper does not see: sales rank, price statistics, dimensions, FBA fees,
category tree and images for every single hit.

```json
{
  "searchKeyword": "wireless headphones",
  "position": 1,
  "asin": "B0CHX1W1XY",
  "title": "Example Wireless Headphones, Black",
  "brand": "ExampleBrand",
  "marketplace": "com",
  "currency": "USD",
  "url": "https://www.amazon.com/dp/B0CHX1W1XY",
  "listPrice": 149.99,
  "categoryTree": [{ "id": 172282, "name": "Electronics" }],
  "salesRanks": [{ "categoryId": 172282, "rank": 1201, "date": "2024-04-05T...Z" }],
  "stats": {
    "current": { "amazon": 89.99, "new": 89.99, "salesRank": 1201, "rating": 4.4, "reviewCount": 8123 },
    "avg90":   { "amazon": 94.20, "new": 92.10, "salesRank": 1380 },
    "lowestEver": { "amazon": { "value": 74.99, "date": "..." } }
  },
  "scrapedAt": "2026-08-21T09:14:02Z"
}
```

***

### What you get

- **Organic results only.** Sponsored products are not in the list, so
  position 1 is the first product Amazon actually ranks for the term.
- **Amazon's ordering, preserved.** `position` is 1, 2, 3 … per keyword.
- **Full product data per hit** — the same record the Amazon Product Data
  Actor returns: title, brand, manufacturer, model, images, category tree,
  sales ranks, EAN/UPC, dimensions and weight, FBA and referral fees,
  coupons, variations, availability, and current / 30 / 90 / 180-day price,
  rating and review statistics.
- **Many keywords per run.** Each term is searched independently.

Switch on **Return ASINs only** if you just need the ranked identifier list —
the output shrinks to `asin`, `url`, `searchKeyword` and `position`, and the
run is noticeably faster. Results cost the same either way.

### Input

| Field | Meaning |
|---|---|
| **Search terms** | One or more keywords. Each is searched separately. |
| **Marketplace** | US, UK, DE, FR, IT, ES, NL, CA, MX, AU, JP, IN. |
| **Maximum results per keyword** | 1 – 50. Defaults to 10. |
| **Return ASINs only** | Identifier list instead of full records. |
| **Statistics period (days)** | Window for the price statistics on each hit, 1 – 365. Free. |
| **Maximum wait for capacity** | How long to wait if shared capacity is momentarily used up. |

#### Brazil is not supported

Keyword search does not cover **amazon.com.br**. The marketplace is not offered
in the dropdown, and a run configured for it stops immediately with a clear
message instead of failing halfway through and billing you for the rest.

#### How deep a search goes

Results are read a page at a time, ten per page. A keyword stops when the page
comes back short, when the last available page is reached, or when your own
cap is hit — whichever happens first. In practice that is **up to 50 results
per keyword**; the sources describing this endpoint quote both 20 and 50, so
this Actor asks for pages until the data itself says there are no more, rather
than assuming either number. You are never charged for a page that returns
nothing.

### Billing

**One charge per result delivered.** Nothing else is billed:

- keywords with no results — reported as a `notFound` item — are free,
- items marked `error` are free,
- items marked `currentlyUnavailable` (shared capacity momentarily used up)
  are free; the run still finishes successfully and you can retry in a few
  minutes,
- invalid catalogue entries returned by the index are reported but not
  charged.

The data source prices a *search*, not a page. Because the endpoint
documentation does not describe paging at all, this Actor assumes the
pessimistic reading — that each page request is priced like a full search —
when it reserves capacity. That only affects how carefully it queues its
requests, never what you are charged.

Every run also writes a **`RUN_SUMMARY`** record with `requested`,
`delivered`, `notFound`, `unavailable`, `failed` and `unitsSpent`.

### Notes

- Consecutive pages can overlap when Amazon reshuffles its ranking mid-run.
  Duplicate ASINs are removed per keyword, so positions stay dense and unique.
- Missing values are omitted rather than filled with `0` or `null`, so an
  absent price means "no offer", never "free".
- Prices are always in the marketplace's own currency, given as a number plus
  a separate `currency` field. Japanese yen has no decimal places.

### Related

- **Amazon Product Data** — full records for ASINs you already have.
- **Amazon Product Finder** — find ASINs by price, rank, rating, category and
  historical criteria instead of by keyword.

# Actor input Schema

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

What to type into the Amazon search box. Each term is searched separately and billed separately; every result you get back is one charge.

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

Which Amazon marketplace to search. Prices and currency always follow the marketplace you pick. Brazil is not covered by keyword search.

## `maxResultsPerKeyword` (type: `integer`):

How many hits to keep per search term, at most 50 - that is as deep as Amazon's result list can be read here. Billing is one charge per result delivered.

## `asinsOnly` (type: `boolean`):

Skip the product details and return just the ASIN, the URL and the position for each hit. Faster and much smaller output - use it when you only need the result list. Results are charged the same either way.

## `statsDays` (type: `integer`):

Time window for the price statistics on each result: current, average, lowest and highest price over this many days. Free of charge - it is computed from history that already exists. Ignored when "Return ASINs only" is on.

## `maxWaitSeconds` (type: `integer`):

If the shared data capacity is momentarily used up, wait up to this long for it to refill. Anything still unserved afterwards is reported as currently unavailable - and never charged.

## `apiKey` (type: `string`):

Advanced: run this Actor against your own upstream account instead of the bundled capacity. Leave empty to use the included capacity.

## Actor input object example

```json
{
  "keywords": [
    "wireless headphones"
  ],
  "marketplace": "com",
  "maxResultsPerKeyword": 10,
  "asinsOnly": false,
  "statsDays": 90,
  "maxWaitSeconds": 60
}
```

# 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 = {
    "keywords": [
        "wireless headphones"
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("cyprusapi/amazon-keyword-search").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 headphones"] }

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

```

## MCP server setup

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

```

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/tIRyGdI7w7ljMYphT/builds/rgot3wWNnRWMyWhTh/openapi.json