# Best Sellers

Source: https://env.7xmtools.com/api-docs/best-sellers.html

Retrieve an ASIN list of the most popular products based on sales in a specific category or product group, ordered starting with the best-selling product.

GET · 50 tokens per request

The Best Sellers request returns an ASIN list of the most popular products based on sales in a specific category or product group.

> **Note:** Keepa cannot always correctly identify the sales rank reference category, so some products may be misplaced.

## List types & behavior

- **Root category lists** (e.g., “Home & Kitchen”) contain up to **500,000** ASINs. For a list of all available root categories, use the [Category Lookup](https://env.7xmtools.com/api-docs/category-lookup.html) with the `categoryId` **0**.
- **Sub-category lists** (e.g., “Home Entertainment Furniture”) contain up to **10,000** ASINs. By default, sub-category lists are created based on the product’s primary sales rank and do not reflect the actual ordering on Amazon. See the [`sublist` parameter](https://env.7xmtools.com/api-docs/best-sellers.html#param-sublist).
- **Product group lists** (e.g., “Beauty”) contain up to **500,000** ASINs. A product group is identified by the `websiteDisplayGroupName` field of the [product object](https://env.7xmtools.com/api-docs/product-object.html).
- **Updates:** Lists are usually updated hourly.
- **Ordering:** Lists are ordered starting with the best-selling product. Since lists are cached for up to one hour, the ordering may be outdated.
- **Exclusions:** Products without an accessible sales rank are not included.

## Endpoint

```
GET https://api.keepa.com/bestsellers?key=<yourAccessKey>&domain=<domainId>&category=<categoryId>&range=<range>
```

## Parameters

| Parameter | Required | Description |
| --- | --- | --- |
| `key` | required | Your private API key. |
| `domain` | required | Integer value for the Amazon locale you want to access. See the [valid domain IDs](https://env.7xmtools.com/api-docs/best-sellers.html#domain-ids) below. |
| `category` | required | The category node ID for which you want the best sellers list. You can find category node IDs via the [Category Search](https://env.7xmtools.com/api-docs/category-search.html), the [Deals](https://env.7xmtools.com/deals) page (select the category and click on “Show API query”), or directly on Amazon. Alternatively, you can provide a product group (e.g., `Beauty`), which can be found in the `websiteDisplayGroupName` field of the [product object](https://env.7xmtools.com/api-docs/product-object.html). |
| `range` | optional | Retrieve a best seller list based on a sales rank average instead of the current sales rank. Valid values: **0** (use current rank), **30** (30-day average), **90** (90-day average), **180** (180-day average). |
| `month` & `year` | optional | Request a historical best seller list for a specific month. Both parameters must be specified together; must not be combined with `range`. See [details](https://env.7xmtools.com/api-docs/best-sellers.html#param-month-year). |
| `variations` | optional | Controls whether items with multiple variations are returned as a single representative variation or as all variations. See [details](https://env.7xmtools.com/api-docs/best-sellers.html#param-variations). |
| `sublist` | optional | Create the best seller list based on the sub-category sales rank instead of the primary sales rank. See [details](https://env.7xmtools.com/api-docs/best-sellers.html#param-sublist). |

### Valid domain IDs

| Domain ID | Locale |
| --- | --- |
| **1** | com |
| **2** | co.uk |
| **3** | de |
| **4** | fr |
| **5** | co.jp |
| **6** | ca |
| **8** | it |
| **9** | es |
| **10** | in |
| **11** | com.mx |
| **12** | com.br |

### `month` & `year`

Request a historical best seller list for a specific month, based on the average rank during that month. Keepa maintains lists for the last **36 months**. Requests for the current calendar month or any month beyond 36 months ago are not permitted.

> **Note:** If using these parameters, both `month` and `year` must be specified. The `range` parameter must not be used concurrently.

| Parameter | Valid values |
| --- | --- |
| `month` | Integer between **1** and **12**, representing January to December. |
| `year` | 4-digit year (e.g., **2024**). |

Examples: `month=6&year=2024` (June 2024), `month=11&year=2023` (November 2023).

### `variations`

Controls whether items with multiple variations are returned as a single representative variation or as all variations.

By default, one variation per parent is returned, restricting list entries to a single variation. If the variations share the same sales rank, the representative is the variation with the highest monthly units sold (if that data point is available). If monthly sold data is missing or tied, the representative falls back to a randomly picked one.

| Value | Behavior |
| --- | --- |
| **0** | Collapse to one variation per parent (default). Selection rule: sales rank, then highest monthly units sold. |
| **1** | Return all variations. |

### `sublist`

By default, the best seller list for sub-categories is created based on the product’s primary sales rank, if available. To request a best seller list based on the sub-category sales rank (classification rank), use the `sublist` parameter with the value **1**. The `range`, `month`, and `year` parameters must not be used concurrently.

> **Note:** Not all products have a primary sales rank or a sub-category sales rank, and not all sub-category levels have sales ranks.

| Value | Behavior |
| --- | --- |
| **0** | List is based on the primary rank (default). |
| **1** | List is based on the sub-category rank. |

## Token Cost

A Best Sellers request costs a flat **50 tokens**.

- If **no list** for the specified category and locale exists in Keepa’s system, the response will be empty and **no tokens** will be consumed.
- If a **valid list** is found but contains zero products (an empty list), the token cost of **50** will still be deducted from your account. Tokens are consumed based on the successful execution and delivery of the query results, regardless of the number of ASINs returned in the list.

## Response

The response contains a `bestSellersList` field with a [Best Sellers object](https://env.7xmtools.com/api-docs/best-sellers-object.html). If no list for the specified category and locale exists in Keepa’s system, the response will be empty and no tokens will be consumed.

## Examples

### Best sellers of a category

Retrieve the current best sellers list of the “Camera & Photo” category (node `281052`) on amazon.com:

```
https://api.keepa.com/bestsellers?key=YOUR_API_KEY&domain=1&category=281052
```

**Java**

```java
KeepaAPI api = new KeepaAPI("YOUR_API_KEY");
Request r = Request.getBestSellersRequest(AmazonLocale.US, 281052);
api.sendRequest(r)
    .done(result -> {
        String[] asins = result.bestSellersList.asinList;
        System.out.println("Best seller: " + asins[0]);
    })
    .fail(failure -> System.out.println(failure));
```

**PHP**

```php
<?php
use Keepa\KeepaAPI;
use Keepa\API\Request;
use Keepa\API\ResponseStatus;
use Keepa\objects\AmazonLocale;

$api = new KeepaAPI("YOUR_API_KEY");
$response = $api->sendRequestWithRetry(Request::getBestSellerRequest(AmazonLocale::US, "281052"));
if ($response->status == ResponseStatus::OK) {
    print_r($response->bestSellersList->asinList);
}
```

**Python**

```python
import requests

params = {"key": "YOUR_API_KEY", "domain": 1, "category": 281052}
r = requests.get("https://api.keepa.com/bestsellers", params=params)
data = r.json()

best_sellers = data["bestSellersList"]["asinList"]
print(f"Top ASIN: {best_sellers[0]} ({len(best_sellers)} ASINs total)")
```

**Node.js**

```javascript
const res = await fetch("https://api.keepa.com/bestsellers?key=YOUR_API_KEY&domain=1&category=281052");
const data = await res.json();

const bestSellers = data.bestSellersList.asinList;
console.log(`Top ASIN: ${bestSellers[0]} (${bestSellers.length} ASINs total)`);
```

**cURL**

```bash
curl -s "https://api.keepa.com/bestsellers?key=YOUR_API_KEY&domain=1&category=281052"
```

### Example response

```json
{
  "timestamp": 1753641000000,
  "tokensLeft": 4250,
  "refillIn": 32000,
  "refillRate": 300,
  "tokenFlowReduction": 0,
  "tokensConsumed": 50,
  "processingTimeInMs": 21,
  "bestSellersList": {
    "domainId": 1,
    "lastUpdate": 7663320,
    "categoryId": 281052,
    "asinList": [
      "B0F3GWXLTS",
      "B0BDHWDR12",
      "B07XJ8C8F5",
      "B08N5WRWNW",
      "B09G9FPHY6",
      "B01M8L5Z3Y",
      "B07PGL2ZSL",
      "B0863TXGM3"
    ]
  }
}
```

*Response shortened for readability; illustrative values.* A real root category list can contain up to 500,000 ASINs. `lastUpdate` is in Keepa Time minutes.

### Other request modes

Best sellers based on the **90-day sales rank average** instead of the current rank:

```
https://api.keepa.com/bestsellers?key=YOUR_API_KEY&domain=1&category=281052&range=90
```

**Historical** best sellers list for June 2024 (average rank during that month; `range` must not be used concurrently):

```
https://api.keepa.com/bestsellers?key=YOUR_API_KEY&domain=1&category=281052&month=6&year=2024
```

Best sellers of a **product group**, passing the `websiteDisplayGroupName` value from the [product object](https://env.7xmtools.com/api-docs/product-object.html) instead of a category node ID:

```
https://api.keepa.com/bestsellers?key=YOUR_API_KEY&domain=1&category=Beauty
```

Sub-category list based on the **sub-category sales rank** (classification rank) instead of the primary rank, including **all variations**:

```
https://api.keepa.com/bestsellers?key=YOUR_API_KEY&domain=1&category=3236451011&sublist=1&variations=1
```