# Amazon Best Sellers & Rankings Scraper (`nimbryxo-studio/amazon-best-sellers-and-rankings-scraper`) Actor

Scrape Amazon's Best Sellers, New Releases, Most Wished For, Most Gifted and Movers & Shakers charts. Get rank, ASIN, title, price, rating and category for every product on a chart, with optional deeper category coverage.

- **URL**: https://apify.com/nimbryxo-studio/amazon-best-sellers-and-rankings-scraper.md
- **Developed by:** [Nimbryxo-studio](https://apify.com/nimbryxo-studio) (community)
- **Categories:** E-commerce, Automation, Lead generation
- **Security:** Limited permissions
- **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 Best Sellers & Rankings Scraper

Scrape **Amazon's chart family** -- Best Sellers, New Releases, Most Wished For, Most Gifted, and Movers & Shakers -- for any category on any Amazon marketplace. Get rank, ASIN, title, price, rating, and category for every product Amazon currently exposes on a chart, with optional recursion into subcategories and optional product-detail enrichment.

### What this actor does

- **Five chart types:** Best Sellers, New Releases, Most Wished For, Most Gifted, Movers & Shakers
- **Any category:** pass a category slug (`electronics`), a slug + browse-node ID (`electronics/172541`), or paste a full Amazon chart URL
- **Category-tree recursion:** optionally walk each category's subcategory links up to a configurable depth, scraping every subcategory's own chart too
- **20 Amazon marketplaces:** amazon.com, .co.uk, .de, .fr, .it, .es, .ca, .com.au, .co.jp, .in, .com.br, .com.mx, .nl, .se, .pl, .com.tr, .ae, .sa, .sg, .eg
- **Honest empty-chart handling:** Movers & Shakers legitimately has no items for many categories -- the actor emits a clear chart-metadata record instead of silently returning zero items or substituting unrelated products
- **Empty fields are omitted**

### Output per chart item

- `rank` -- position on the chart
- `asin` -- Amazon Standard Identification Number
- `title`, `url`, `image`
- `price` -- `{value, currency, display}` (only emitted when Amazon shows an explicit price)
- `stars`, `reviewsCount`
- `badge` -- e.g. `BestSeller`, `AmazonsChoice` (only when Amazon shows one)
- `format` -- format/variant summary, e.g. `"Paperback"` or `"4 formats available"` (books/media charts only, when Amazon's card shows one)
- `chartType`, `category`, `categoryNodeId`, `categoryUrl`, `page`
- `rankChangeDirection`, `rankChangeAmount` -- Movers & Shakers only, and only when Amazon's own rank-change marker is present
- `listPrice`, `inStock` -- only when `includeProductDetails` is enabled, and only when the product's own detail page shows explicit crossed-out list-price or in-stock/out-of-stock evidence (never inferred)
- `childCategories` -- sibling/child category links `{name, path, url, nodeId}` from the chart page's own category nav, when present (e.g. "Camera & Photo", "Computers & Accessories" under Electronics)
- `recordType: "chartItem"`, `scrapedAt`

### Output: chart metadata record

Emitted once per category when a chart is empty or a page cannot be loaded, instead of returning zero items silently:

- `chartType`, `category`, `categoryNodeId`, `categoryUrl`, `domain`
- `extractedItemCount` -- how many items were actually extracted (0 for an empty/failed chart)
- `message` -- human-readable explanation (e.g. "No items currently available for this chart/category.")
- `recordType: "chartMetadata"`, `scrapedAt`

### Input

| Field | Type | Default | Description |
|---|---|---|---|
| `chartType` | string | `bestSellers` | `bestSellers` / `newReleases` / `mostWishedFor` / `mostGifted` / `moversAndShakers` |
| `domain` | string | `amazon.com` | Which Amazon marketplace to scrape |
| `categoryUrls` | array | `["electronics"]` | Category slugs, slug/nodeId pairs, or full chart URLs |
| `categoryNodeIds` | array | `[]` | Additional `rootSlug/nodeId` entries |
| `maxDepth` | int | `0` | Subcategory recursion depth (0-3) |
| `startPage` | int | `1` | First chart page to fetch |
| `maxPages` | int | `2` | Max chart pages to fetch per category |
| `maxItemsPerCategory` | int | `60` | Hard cap on items per category |
| `maxItems` | int | `200` | Hard cap on total items across the run |
| `includeProductDetails` | boolean | `false` | Enrich items with product-detail-page data |
| `maxProductDetails` | int | `10` | Cap on product-detail fetches when enabled |
| `proxyConfiguration` | object | AUTO | Apify proxy (datacenter by default) |

#### Example: Best Sellers in Electronics

```json
{
  "chartType": "bestSellers",
  "categoryUrls": ["electronics"],
  "maxItems": 50
}
```

#### Example: New Releases for a specific subcategory (Headphones)

```json
{
  "chartType": "newReleases",
  "categoryUrls": ["electronics/172541"],
  "maxItems": 30
}
```

#### Example: recurse a whole department's subcategories

```json
{
  "chartType": "bestSellers",
  "categoryUrls": ["electronics"],
  "maxDepth": 2,
  "maxItemsPerCategory": 20,
  "maxItems": 500
}
```

#### Example: Movers & Shakers on the UK marketplace

```json
{
  "chartType": "moversAndShakers",
  "domain": "amazon.co.uk",
  "categoryUrls": ["electronics"]
}
```

### Use cases

- **Market research** -- track which products dominate a category's chart over time
- **Competitive intelligence** -- monitor a competitor's category ranking and pricing
- **Trend spotting** -- New Releases and Movers & Shakers surface emerging products before they're widely known
- **Gift-guide content** -- Most Gifted and Most Wished For power seasonal buying-guide content
- **Category research** -- recurse a department's full subcategory tree to map an entire vertical's top products

### FAQ

**Is this actor affiliated with Amazon?**
No. This is a third-party actor that scrapes Amazon's public chart pages.

**Does the actor guarantee "Top 100" for every category?**
No. The actor extracts all chart items Amazon currently exposes up to your `maxPages`/`maxItemsPerCategory` limits in a single session. Amazon's own pagination does not reliably expose a fixed rank count on every category, so the actor never claims a guaranteed top-N -- check `extractedItemCount` on the chart-metadata record to see how many items were actually found.

**Why is Movers & Shakers sometimes empty?**
Amazon itself frequently has no movers-and-shakers data for a given category at a given time -- this is a real, documented state on Amazon's own site, not a scraper bug. The actor emits a chart-metadata record explaining this instead of guessing or substituting unrelated recommended products.

**Why do some items have no `price` or `rating`?**
Amazon only shows these when they exist on the chart card. The actor never fabricates a price or rating -- if the field is missing, it's omitted from the record entirely.

**How is `rank` different from position across separate runs?**
`rank` reflects Amazon's own displayed chart position at scrape time. The actor holds no state between runs, so `rankChangeDirection`/`rankChangeAmount` (Movers & Shakers only) are populated strictly from Amazon's own rank-change marker on the page, never inferred by comparing separate runs.

**Does the actor need a proxy?**
No -- it uses Apify's free AUTO (datacenter) proxy by default, which works for the large majority of requests. If a session gets repeatedly blocked, the actor automatically escalates to a residential proxy session as a fallback.

**Can I scrape a whole department's subcategories in one run?**
Yes -- set `maxDepth` to 1-3 and the actor walks each category's subcategory links (visible in Amazon's own left-nav) that many levels deep, scraping each subcategory's own chart.

# Actor input Schema

## `chartType` (type: `string`):

Which Amazon chart to scrape.

## `domain` (type: `string`):

Which Amazon marketplace to scrape the chart from.

## `categoryUrls` (type: `array`):

Amazon category slugs (e.g. `electronics`, `electronics/172541`) or full chart URLs to scrape. Each entry is combined with `chartType` and `domain` to build the chart page.

## `categoryNodeIds` (type: `array`):

Amazon browse-node IDs in `rootSlug/nodeId` form (e.g. `electronics/172541` for Headphones). Combined with `categoryUrls` if both are provided.

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

When > 0, also walk each category's left-nav subcategory links this many levels deep, scraping each subcategory's own chart too. 0 = only the given categories.

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

First chart page to fetch (each page is a separate ranked page on Amazon's site, not a fixed rank count).

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

Maximum number of chart pages to fetch per category, starting at `startPage`.

## `maxItemsPerCategory` (type: `integer`):

Hard cap on chart items emitted per category (across all its pages).

## `maxItems` (type: `integer`):

Hard cap on total chart items emitted across all categories in this run.

## `includeProductDetails` (type: `boolean`):

For each chart item, also fetch its product detail page for purchase-option and additional rating data. Slower and bounded by `maxProductDetails`.

## `maxProductDetails` (type: `integer`):

Hard cap on how many chart items get product-detail enrichment when `includeProductDetails` is on.

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

Apify proxy used to fetch chart pages. Datacenter (AUTO) is used by default and works for most requests; the actor escalates to residential only after repeated blocks on a session.

## Actor input object example

```json
{
  "chartType": "bestSellers",
  "domain": "amazon.com",
  "categoryUrls": [
    "electronics"
  ],
  "categoryNodeIds": [],
  "maxDepth": 0,
  "startPage": 1,
  "maxPages": 2,
  "maxItemsPerCategory": 20,
  "maxItems": 20,
  "includeProductDetails": false,
  "maxProductDetails": 5,
  "proxyConfiguration": {
    "useApifyProxy": true
  }
}
```

# Actor output Schema

## `chartItems` (type: `string`):

Dataset containing all scraped Amazon chart items and chart-metadata records.

# 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 = {
    "chartType": "bestSellers",
    "domain": "amazon.com",
    "categoryUrls": [
        "electronics"
    ],
    "categoryNodeIds": [],
    "maxDepth": 0,
    "startPage": 1,
    "maxPages": 2,
    "maxItemsPerCategory": 20,
    "maxItems": 20,
    "includeProductDetails": false,
    "maxProductDetails": 5,
    "proxyConfiguration": {
        "useApifyProxy": true
    }
};

// Run the Actor and wait for it to finish
const run = await client.actor("nimbryxo-studio/amazon-best-sellers-and-rankings-scraper").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 = {
    "chartType": "bestSellers",
    "domain": "amazon.com",
    "categoryUrls": ["electronics"],
    "categoryNodeIds": [],
    "maxDepth": 0,
    "startPage": 1,
    "maxPages": 2,
    "maxItemsPerCategory": 20,
    "maxItems": 20,
    "includeProductDetails": False,
    "maxProductDetails": 5,
    "proxyConfiguration": { "useApifyProxy": True },
}

# Run the Actor and wait for it to finish
run = client.actor("nimbryxo-studio/amazon-best-sellers-and-rankings-scraper").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 '{
  "chartType": "bestSellers",
  "domain": "amazon.com",
  "categoryUrls": [
    "electronics"
  ],
  "categoryNodeIds": [],
  "maxDepth": 0,
  "startPage": 1,
  "maxPages": 2,
  "maxItemsPerCategory": 20,
  "maxItems": 20,
  "includeProductDetails": false,
  "maxProductDetails": 5,
  "proxyConfiguration": {
    "useApifyProxy": true
  }
}' |
apify call nimbryxo-studio/amazon-best-sellers-and-rankings-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,nimbryxo-studio/amazon-best-sellers-and-rankings-scraper"
        }
    }
}
```

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/0FAIaQmKaKgbU4Ftg/builds/ERhYC4a3fFU4C7GYC/openapi.json