Amazon Best Sellers API: Daily BSR Snapshot from HTML Charts
Amazon's Best Sellers URL is a shopper page with no export. Fifty tiles, a department crumb, a pager. Rank is a number the layout paints. The ASIN is a fragment of a product href. Map those nodes with a scraper and you will fill a sheet until a wrapper class moves — then the job writes empty rows while a browser still shows the same fifty cards. The chart did not vanish. The CSS contract did.
Movers & Shakers, New Releases, Most Wished For and Gift Ideas are the same object: HTML for a click, not a feed you subscribe to. This recipe does not walk a signup form and it does not catalog every Amazon route. It ships one named artifact — a daily snapshot file, one category, one chart type, one marketplace, keyed by ASIN. best-sellers is the GET that fills it. Opening this page or copying a snippet does not send that GET.
Sign in, copy an authorized platform key from the dashboard, and read it from OPENDATA_API_KEY on the server that writes the file. Examples that show YOUR_API_KEY are placeholders. The key rides in the query string, so those URLs do not belong in tickets, screenshots, or browser JavaScript.
Charts that only exist as HTML
Amazon publishes five ranked lists as documents. BEST_SELLERS is recent sales inside a department. NEW_RELEASES is new and upcoming titles that are already selling. MOVERS_AND_SHAKERS is the largest twenty-four-hour rank moves. MOST_WISHED_FOR is wish-list and registry adds. GIFT_IDEAS is products bought as gifts. Print any of them and you still have a page.
What a parse would have kept off a tile is also what the JSON carries: rank, asin, product_title, product_price, product_star_rating, product_num_ratings, product_url, product_photo. Movers & Shakers adds rank_change_label for the climb or drop versus the prior period. Charts without that label will not draw a sparkline from a single pull. category_name is the resolved department string. Archive it. The path you typed (software/229535) and the crumb on the page can disagree later, and the returned name is what you reconcile against.
A scraper owns CSS. This call owns query parameters. Status is still two layers, and they are not interchangeable. HTTP 4xx/5xx means the request did not run — missing key, quota, or network. Inspect credentials and credits only on that layer. The gateway envelope is {code, message, data}. code 200 means the platform accepted the call. It does not mean fifty products arrived. A category path that marketplace does not use, or a chart the site is not showing that day, comes back accepted with products empty or missing. Treat that as a miss. Do not retry the same path in a tight loop, and do not treat an empty list as “it will fill in a minute.”
One category, one type, one page of 50
Name the snapshot before you name the request. One job is one category, one chart type, one page. category is required: a top-level slug such as software, or a nested node such as software/229535, copied from the Best Sellers URL you actually watch. Do not invent the numeric node from memory. type defaults to BEST_SELLERS. Pin it in the file header so an unattended cron cannot silently switch charts — a default is fine for a one-off, not for a job that runs without a person.
One page is fifty ranked products. page defaults to 1. Most alerts fire on the first fifty. Page 2 is a second call, a second credit, and a second file. Do not paginate until page 1 writes a clean document. If you later need only identity columns, fields=rank,asin,product_title,product_price,rank_change_label trims the payload. Leave fields off until you know which columns the diff uses.
import os
import requests
BASE = "https://api.opendata-api.com/api/project/amazon/best-sellers"
KEY = os.environ["OPENDATA_API_KEY"].strip()
def fetch_chart(category, chart_type, country="US", page=1):
resp = requests.get(
BASE,
params={
"key": KEY,
"category": category,
"type": chart_type,
"country": country,
"page": page,
},
timeout=30,
)
resp.raise_for_status() # HTTP layer: 4xx/5xx is transport or quota
envelope = resp.json()
if str(envelope.get("code")) != "200":
raise RuntimeError(envelope.get("message"))
data = envelope.get("data") or {}
products = data.get("products")
if products is None:
products = []
return data, products
This guide uses software with MOVERS_AND_SHAKERS because the movement label lives on that chart. The Best Sellers pull of the same category is a different file. Merging two type values into one map is how ranks stop meaning anything.
Rotate marketplace without rewriting the job
Every chart is per marketplace. country accepts US (default), GB, DE, FR, IT, ES, NL, SE, PL, BE, IE, CA, MX, BR, AU, JP, IN, SG, AE, SA, EG, ZA, TR, and CN. The function already takes country. Japan electronics New Releases is the same callable with category="electronics", chart_type="NEW_RELEASES", country="JP" — not a second scraper, not a second parser.
Category paths follow the site. A US node may be a different number in Japan, or may not exist. When you add a marketplace, copy the path from that country's own Best Sellers page first. Envelope 200 with empty products is a path problem until proven otherwise; it is not a reason to mint a new key.
Put country in the filename and inside the JSON. US rank 3 and JP rank 3 in one dictionary is a dashboard that lies. You can sit two files next to each other. You cannot fuse them into one “global BSR.” language=en_US changes strings. It does not merge catalogs, and it does not translate a JP ASIN list into a US chart.
The snapshot file you keep
The artifact is one dated JSON file per tuple of country, category, type, and page. The filename carries all four so a directory listing is the index. Key the product map on asin. Keep rank, title, price, rating, rating count, and rank_change_label when the field is present. Rows without an ASIN are skipped; titles are not keys. Write the file even when the list is empty. An empty by_asin means the pull ran and the chart had nothing. That is not the same record as “the job did not run.”
import json
from datetime import date
CATEGORY = "software"
CHART_TYPE = "MOVERS_AND_SHAKERS"
COUNTRY = "US"
PAGE = 1
def main():
data, products = fetch_chart(CATEGORY, CHART_TYPE, COUNTRY, PAGE)
day = date.today().isoformat()
snapshot = {
"date": day,
"category": CATEGORY,
"category_name": data.get("category_name"),
"type": CHART_TYPE,
"country": COUNTRY,
"page": PAGE,
"by_asin": {},
}
for item in products:
asin = item.get("asin")
if not asin:
continue
snapshot["by_asin"][asin] = {
"rank": item.get("rank"),
"title": item.get("product_title"),
"price": item.get("product_price"),
"rating": item.get("product_star_rating"),
"num_ratings": item.get("product_num_ratings"),
"rank_change": item.get("rank_change_label"),
}
slug = CATEGORY.replace("/", "-")
filename = f"bsr-{COUNTRY}-{slug}-{CHART_TYPE}-{day}-p{PAGE}.json"
with open(filename, "w", encoding="utf-8") as handle:
json.dump(snapshot, handle, indent=2, ensure_ascii=False)
print(f"wrote {len(snapshot['by_asin'])} asins to {filename}")
if __name__ == "__main__":
main()
Schedule once per day per tuple you actually watch. Consecutive files give three alert classes: ASINs in today and not yesterday (entries), the reverse (exits), and rank improved past a threshold you set. On Movers & Shakers, rank_change_label already encodes movement, so one file can list the fastest risers without yesterday's copy. The label is not a history. Drop yesterday's file and today's pull cannot rebuild yesterday's ranks.
This snapshot is not a buy box, not an offer count, not a review dump, and not today's deals. product-details can take up to ten ASINs in one call when you later decide a climber is worth sourcing research; do not fan that call out across all fifty rows on every run or the chart job becomes an accidental catalog crawl. products-by-category sizes a department beyond the top fifty — a different artifact. Charts move inside a day; a daily file will miss intra-day spikes. Page 1 is fifty rows, not the long tail. A 200 envelope with empty products is a bad path or an empty chart, not a reason to rotate keys. Parameter notes live on the best-sellers reference; per-request cost is on pricing.