# Best Sellers

> Source: https://scrape.do/documentation/amazon-scraper-api/bestsellers/

Scrape Amazon's Best Sellers and New Releases charts with ranks, prices, and ratings

The Best Sellers endpoint returns Amazon's ranked chart for a category — the Best Sellers list, or the New Releases list with `type=new-releases`. Each entry carries its rank, ASIN, product detail page URL, and, for positions with full cards, price and rating data.

Amazon publishes a Top 100 as two pages of 50. Each page renders full product cards for the first 30 positions and lists the remaining 20 by rank and ASIN only, so the response carries two arrays: `ranking` is the complete ordered chart for the page, and `products` is the subset with full product detail. Join them on `asin`.

---

## Endpoint

```
GET https://api.scrape.do/plugin/amazon/bestsellers
```

---

## Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `token` | string | * | Your Scrape.do API authentication token |
| `category` | string | * | Amazon category slug (e.g., `electronics`). Slugs are marketplace-specific — `electronics` is the Electronics chart on `amazon.com` and `amazon.co.uk`, while on `amazon.de` the same chart is `ce-de`. An unknown slug returns `400 invalid_category`. |
| `geocode` | string | * | Amazon marketplace country code (e.g., `us`, `gb`, `de`, `jp`). `amazon_domain` (e.g., `amazon.de`) is accepted as an alternative. |
| `type` | string | | Chart type: `bestsellers` (default) or `new-releases` |
| `node` | string | | Category node id, narrowing the chart to a sub-category of the slug |
| `page` | integer | | `1` (positions 1-50) or `2` (positions 51-100). Higher values return `400 page_out_of_range`. |
| `zipcode` | string | | Postal code formatted according to country requirements to localize prices. Use either `zipcode` or `countryName`, not both. |
| `countryName` | string | | Country-level location for marketplaces without ZIP-level delivery. |
| `super` | boolean | | Enable residential/mobile proxies for higher success rates. Costs 10x credits (default: `false`) |
| `language` | string | | Language code in ISO 639-1 format (e.g., `EN`, `DE`) |
| `include_html` | boolean | | When `true`, the response includes the full raw HTML of the page after the structured JSON output (default: `false`) |

> [!WARNING]
> The `device` parameter is not supported for this endpoint: Amazon's mobile chart page does not render product data server-side, so `device=mobile` returns `400`.

---

## Response Parameters

| Field | Type | Description |
|-------|------|-------------|
| `category` | string | Echo of the requested category slug |
| `node` | string | Echo of the `node` parameter, when supplied |
| `type` | string | `bestsellers` or `new-releases` |
| `page` | number | Echo of the requested page |
| `ranking` | array | Complete ordered chart for the page — one entry per position, including positions without a product card. Serialized as `[]` when the chart is empty. |
| `products` | array | The subset of `ranking` Amazon rendered full detail for, in chart order. Serialized as `[]` when the chart is empty. |
| `ranking_count` | number | Length of `ranking` |
| `products_count` | number | Length of `products`. Normally 30 on a full chart — this is how many cards Amazon renders, not the chart size. |
| `pagination` | object | `{current_page, has_next}`. Also `false` on page 2 (the last servable page) or when the chart is shorter than a full page. |
| `html` | string | Full raw HTML of the Amazon page (only present when `include_html=true`) |

### Ranking Entry Fields

| Field | Type | Description |
|-------|------|-------------|
| `rank` | number | Absolute position in the chart: 1-50 on page 1, 51-100 on page 2 |
| `asin` | string | Product ASIN number |
| `url` | string | Product detail page URL |

### Product Object Fields

| Field | Type | Description |
|-------|------|-------------|
| `rank` | number | Same rank as the matching `ranking` entry |
| `asin` | string | Product ASIN number |
| `title` | string | The product name exactly as Amazon renders it on the chart card |
| `url` | string | Product detail page URL |
| `imageUrl` | string | Product thumbnail image URL |
| `price` | object | Current price with `currencyCode` and `amount`. Absent when Amazon shows no price. |
| `rating` | object | `value` is the score out of 5 and `count` is the review tally as a number, with the marketplace's own magnitude word resolved — `(23,1 tn)` on `se` becomes `23100` |
| `reviewCount` | string | Localized rating count as displayed |

---

## Example Usage

### Step 1: Pick a Category

Category slugs are per marketplace. Check the category page URL on the Amazon storefront you target (e.g., `amazon.com/gp/bestsellers/electronics` → `electronics`).

### Step 2: Send the API Request

**cURL (API mode)**

```bash
curl --location --request GET 'https://api.scrape.do/plugin/amazon/bestsellers?token=<SDO-token>&category=electronics&geocode=US'
```

**Python (API mode)**

```python
import requests
import json

token = "<SDO-token>"
category = "electronics"
geocode = "US"

url = f"https://api.scrape.do/plugin/amazon/bestsellers?token={token}&category={category}&geocode={geocode}"

response = requests.request("GET", url)

print(json.dumps(response.json(), indent=2))
```

**Node.js (API mode)**

```javascript
const axios = require('axios');

const token = "<SDO-token>";
const category = "electronics";
const geocode = "US";

const url = `https://api.scrape.do/plugin/amazon/bestsellers?token=${token}&category=${category}&geocode=${geocode}`;

axios.get(url)
  .then(response => {
    console.log(JSON.stringify(response.data, null, 2));
  })
  .catch(error => {
    console.error(error);
  });
```

*(Go, Ruby, Java, C#, PHP examples are also available on the HTML version.)*

### Step 3: Receive the Ranked Chart

The API returns the ranked chart plus full detail for the positions Amazon renders cards for:

```json
{
  "category": "electronics",
  "type": "bestsellers",
  "page": 1,
  "ranking": [
    { "rank": 1, "asin": "B08JHCVHTY", "url": "https://www.amazon.com/dp/B08JHCVHTY" },
    { "rank": 2, "asin": "B0GJTFXNRX", "url": "https://www.amazon.com/dp/B0GJTFXNRX" }
  ],
  "products": [
    {
      "rank": 1,
      "asin": "B08JHCVHTY",
      "title": "blink plus plan with monthly auto-renewal",
      "url": "https://www.amazon.com/dp/B08JHCVHTY",
      "imageUrl": "https://images-na.ssl-images-amazon.com/images/I/31YHGbJsldL._AC_UL300_SR300,200_.png",
      "price": {
        "currencyCode": "USD",
        "amount": 11.99
      },
      "rating": {
        "value": 4.4,
        "count": 279563,
        "stars": 4
      },
      "reviewCount": "(279.5K)"
    }
  ],
  "ranking_count": 50,
  "products_count": 30,
  "pagination": {
    "current_page": 1,
    "has_next": true
  }
}
```

### Getting the Full Top 100

Amazon's Top 100 is two pages of 50. Request page 2 for positions 51-100:

```
/plugin/amazon/bestsellers?token=...&category=electronics&geocode=us&page=2
```

Or get the New Releases chart instead:

```
/plugin/amazon/bestsellers?token=...&category=electronics&geocode=us&type=new-releases
```

> [!NOTE]
> `has_next` is `false` whenever the chart is shorter than a full page, so a narrow category does not advertise a page 2 that does not exist.

> [!NOTE]
> A category with no chart returns an empty `ranking` rather than an error — that is a successful response with `ranking_count: 0`. Chart membership changes hourly; two requests minutes apart can legitimately differ.

> [!WARNING]
> Failed requests (upstream failures, unreadable pages) are not charged.