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

Scrapes Amazon keyword search results across 18 marketplaces: organic rank separated from sponsored placements, structured local-currency prices, sales badges, ratings. Batch keywords, filters applied before charging, error items never charged.

- **URL**: https://apify.com/cyprusapi/amazon-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 $3.50 / 1,000 result items

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.
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?

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 Scraper extracts keyword search results from **18 verified Amazon marketplaces** — with the one thing most search scrapers get wrong: **organic rank separated from sponsored placements**. Every product comes with position, organic-only position, sponsored flag, structured price in the marketplace's own currency, rating, review count, sales-volume badge, and more. Batch as many keywords as you like into a single run — they share startup cost. **Or paste Amazon search URLs directly**: apply any filters on Amazon first (Prime, price band, condition, deals, brand) and the actor scrapes exactly that filtered result set — Amazon's own URL filters are applied server-side and passed through untouched.

Built for analysts, sellers, and AI agents: deterministic JSON, documented error semantics, and **you only pay for actual product data** — error items are never charged, and filters apply *before* charging.

### Why this Actor over alternatives?

| | This Actor | Typical competitor |
|---|---|---|
| Sponsored handling | `isSponsored` flag + separate `positionOrganic` rank | sponsored mixed into positions |
| Price output | numeric `{value, currency}` + raw string | string only |
| Billing | per result only — no start fee, no platform usage for you | start fee + per-item + usage fees |
| Filters | stars/reviews/price band, applied **before** charging — plus full Amazon sidebar filters via pasted search URLs | post-processing on your side |
| Batch | many keywords per run | one query per run |
| Errors | pushed for transparency, **never charged** | charged like data |

### Quick start

```json
{
  "keywords": ["anker powerbank 20000mah", "usb c cable 2m"],
  "marketplace": "com",
  "maxPages": 2,
  "sortBy": "RELEVANCE"
}
```

Or a single keyword without the array: `{"query": "laptop", "marketplace": "com"}`.

Or paste Amazon search URLs with your own filters applied — here Prime-only (`rh=p_85:1`) plus a $10–$40 price band:

```json
{
  "searchUrls": [
    {"url": "https://www.amazon.com/s?k=usb+c+cable+2m&rh=p_85%3A1&low-price=10&high-price=40"}
  ],
  "maxPages": 2
}
```

URL mode unlocks every filter Amazon offers in its sidebar (Prime, condition, deals, brand, price band…) — set them on amazon.com, copy the URL, done. The domain in each URL selects the marketplace (any of the 18), so one run can mix marketplaces. Keywords and URLs can be combined in the same run; at least one of them is required.

### Input reference

| Field | Type | Default | Description |
|---|---|---|---|
| `keywords` | string\[] | — | Search keywords — batch as many as you like |
| `query` | string | — | Single-keyword convenience field (used when `keywords` is empty) |
| `searchUrls` | array | — | Amazon search URLs to scrape directly (`[{"url": "…"}]` or plain strings). Apply filters on Amazon first — `rh`, `s`, `low-price`, `high-price` etc. pass through untouched. The URL's domain selects the marketplace; unknown domains produce a free `invalid_url` error item |
| `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 (keyword mode only — URL mode reads it from the URL) |
| `maxPages` | integer | 1 | Pages per keyword/URL (1–20) |
| `startPage` | integer | 1 | First page to scrape (continue a previous run) |
| `sortBy` | string | `RELEVANCE` | `RELEVANCE` | `LOWEST_PRICE` | `HIGHEST_PRICE` | `REVIEWS` | `NEWEST` | `BEST_SELLERS` |
| `language` | string | marketplace default | Amazon locale override (e.g. `en_US`) |
| `excludeSponsored` | boolean | false | Skip sponsored cards entirely |
| `minStars` / `minReviews` | number | 0 | Rating/review filters — before charging |
| `minPrice` / `maxPrice` | number | 0 | Price band in marketplace currency — before charging |
| `proxyConfiguration` | object | bundled geo proxies | Optional — the actor ships with bundled geo proxies per marketplace (no setup needed, we cover the cost). Enable this only to force your own or Apify proxies instead |
| `proxiesByMarketplace` | object | — | Bring-your-own geo-pinned proxies per marketplace; overrides the bundled pool for the listed marketplaces |

### Output

One dataset item per product card:

```json
{
  "source": "amazon_search",
  "searchQuery": "anker powerbank 20000mah",
  "searchUrl": null,
  "page": 1,
  "position": 4,
  "positionOrganic": 3,
  "positionSponsored": null,
  "isSponsored": false,
  "asin": "B0C2345678",
  "title": "Anker Power Bank, 20,000mAh …",
  "price": { "value": 39.99, "currency": "USD" },
  "priceString": "$39.99",
  "originalPriceString": "$49.99",
  "stars": 4.6,
  "reviewsCount": 12847,
  "salesVolumeText": "10K+ bought in past month",
  "isBestSeller": true,
  "isAmazonsChoice": false,
  "badgeTexts": ["Best Seller"],
  "imageUrl": "https://m.media-amazon.com/images/I/…jpg",
  "productUrl": "https://www.amazon.com/dp/B0C2345678",
  "marketplace": "com",
  "totalProductsAvailable": 106379,
  "scrapedAt": "2026-08-16T12:00:00Z"
}
```

**Reading positions:** `position` counts every card in DOM order (including ads); `positionOrganic` counts only non-sponsored cards — the rank that matters for SEO and rank tracking. `positionSponsored` is the 1-based rank among the sponsored cards of the page (sponsored placements are interleaved with organic cards; there is no separate ad block) — `null` on organic cards, just as sponsored cards have `positionOrganic: null`. A `null` field means "not rendered by Amazon" — never a guess.

**Keyword vs URL mode:** items carry both `searchQuery` and `searchUrl` — exactly one is set. Keyword items have `searchQuery` (and `searchUrl: null`); items scraped from a pasted URL have `searchUrl` with the exact source URL (and `searchQuery: null`). Everything else in the item is identical across both modes.

### Error items (never charged)

| `error` | Meaning | Action |
|---|---|---|
| `transport` | Navigation failed (proxy/timeout) | just retry |
| `blocked` | Bot detection after automatic retries across the proxy tier chain (own pool → Apify DC → Apify residential) | use residential/geo-pinned proxies |
| `not_found` | Amazon returned 404 | check input |
| `invalid_url` | `searchUrls` entry has an unknown Amazon domain (not one of the 18 marketplaces) | fix the URL — only that entry is skipped, the run continues |

An empty result page simply ends pagination — zero items, zero charges, no fake error.

### Pricing

Pay per **result** event — one per product item pushed. No start fee, no platform-usage charge for you, errors free, filters apply before charging. Example: 5 keywords × 2 pages ≈ 300–400 items ≈ 300–400 events. See the Pricing tab for the current price.

### Use with AI agents (MCP)

Actor identity: `cyprusapi/amazon-search`. Tool description: search Amazon by keyword on 18 marketplaces and return structured product cards with organic-vs-sponsored rank separation and local-currency prices.

> Example prompt: "Search Amazon.com for 'wireless earbuds', top 2 pages, only products above 4 stars, exclude ads." → input: `{"keywords": ["wireless earbuds"], "marketplace": "com", "maxPages": 2, "minStars": 4, "excludeSponsored": true}`

**Output interpretation for agents:** use `positionOrganic` for ranking analysis (ads never occupy it); `price.value` is numeric and marketplace-local (safe for arithmetic); items with an `error` field are uncharged failures, not data.

### FAQ & limitations

- **How many items per page?** Amazon renders ~16–48 cards depending on layout — variance is normal.
- **Sales badges** ("5K+ bought in past month") are captured verbatim where rendered (de/com/fr/it/es phrase sets; other locales return `null`).
- Amazon caps search depth near page 20 — a platform limit, not ours.
- **Legality:** public search pages only. You are responsible for complying with Amazon's Terms of Service and applicable law.
- Found a bug or need another marketplace? Open an issue — selector maintenance is part of the product.

# Actor input Schema

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

Search keywords or phrases. Batch them: many keywords in one run share startup cost. Also accepts a single keyword via 'query'.

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

Convenience field for one keyword — used when 'keywords' is empty.

## `searchUrls` (type: `array`):

Amazon search result URLs to scrape directly. Apply any filters on Amazon first (Prime, price band, condition, deals, brand…) and paste the URL — Amazon's own query params (rh, s, low-price, high-price, …) are server-side filters and pass through untouched. The domain sets the marketplace and must be one of the 18 supported (unknown domains yield a free error item). Combine freely with keywords; at least one of keywords/query/searchUrls is required.

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

Amazon marketplace to search on.

## `maxPages` (type: `integer`):

Search result pages to scrape per keyword or search URL (Amazon renders ~16-48 cards per page).

## `startPage` (type: `integer`):

First result page to scrape (for continuing a previous run).

## `sortBy` (type: `string`):

Amazon's own sort order for the result pages.

## `language` (type: `string`):

Optional Amazon locale parameter (e.g. 'en\_US', 'de\_DE'). Default: the marketplace's own language.

## `excludeSponsored` (type: `boolean`):

Skip sponsored cards entirely (they never occupy organic rank positions either way).

## `minStars` (type: `number`):

Only push products with at least this rating (0 = no filter). Applied before charging.

## `minReviews` (type: `integer`):

Only push products with at least this many reviews (0 = no filter). Applied before charging.

## `minPrice` (type: `number`):

Only push products at/above this price in marketplace currency (0 = no filter). Applied before charging.

## `maxPrice` (type: `number`):

Only push products at/below this price in marketplace currency (0 = no filter). Applied before charging.

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

Optional — the actor ships with bundled geo proxies per marketplace (no setup needed, we cover the cost). Enable this only to force your own or Apify proxies instead.

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

Optional geo-pinned proxies per marketplace ({"com": \["http://…"], …}). Prevents wrong-currency results and geo 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.

## Actor input object example

```json
{
  "keywords": [
    "anker powerbank 20000mah"
  ],
  "searchUrls": [
    {
      "url": "https://www.amazon.com/s?k=usb+c+cable+2m&rh=p_85%3A1&low-price=10&high-price=40"
    }
  ],
  "marketplace": "com",
  "maxPages": 1,
  "startPage": 1,
  "sortBy": "RELEVANCE",
  "excludeSponsored": false,
  "minStars": 0,
  "minReviews": 0,
  "minPrice": 0,
  "maxPrice": 0,
  "proxyConfiguration": {
    "useApifyProxy": false
  }
}
```

# 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": [
        "anker powerbank 20000mah"
    ],
    "searchUrls": [
        {
            "url": "https://www.amazon.com/s?k=usb+c+cable+2m&rh=p_85%3A1&low-price=10&high-price=40"
        }
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("cyprusapi/amazon-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": ["anker powerbank 20000mah"],
    "searchUrls": [{ "url": "https://www.amazon.com/s?k=usb+c+cable+2m&rh=p_85%3A1&low-price=10&high-price=40" }],
}

# Run the Actor and wait for it to finish
run = client.actor("cyprusapi/amazon-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": [
    "anker powerbank 20000mah"
  ],
  "searchUrls": [
    {
      "url": "https://www.amazon.com/s?k=usb+c+cable+2m&rh=p_85%3A1&low-price=10&high-price=40"
    }
  ]
}' |
apify call cyprusapi/amazon-search --silent --output-dataset

```

## MCP server setup

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