Best Sellers

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

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 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.
• 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.
• 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#

Parameters#

Valid domain IDs#

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.

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.

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.

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. 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

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
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);
}

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)")

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 -s "https://api.keepa.com/bestsellers?key=YOUR_API_KEY&domain=1&category=281052"

Example response#

{
  "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 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