Pinned snapshots: when we deliberately don't auto-refresh

Most of the data on Ranking Countries updates itself. A scheduled job runs weekly, calls the official APIs of the World Bank, WHO, OECD, CDC, BLS and friends, and commits whatever they currently publish. If a statistical office revises a number on Tuesday, our copy follows within the week. The sources page labels these sources "refreshed weekly", with the date of the last pull.

But some of our datasets are the opposite: pinned snapshots — fixed files from one specific edition of a source, with full citations, that a robot is not allowed to touch. They change only when a human reviews them, roughly once a year. Here's why freezing data is sometimes the more honest choice.

Some data has editions, not feeds

An API-shaped worldview assumes data flows continuously. Plenty of the world's best data doesn't — it is published in discrete editions, like books.

PISA, the OECD's international student assessment behind our pupil performance measure, runs roughly every three years. Our figures are the PISA 2022 mathematics results — 81 countries and economies — and there is nothing to refresh until the next cycle's results arrive. Re-downloading weekly would just re-download the same test.

The Yale Environmental Performance Index, behind our country environment scores, ships a new edition every two years. We carry the 2026 edition, covering 177 countries; the next is expected in 2028.

For these, "is it current?" is the wrong question. The right one is "is it the latest edition?" — and that's a question for an annual review, not a cron job.

Sometimes the honest number is the older number

Our country gun deaths figures are pinned to the 2019 Global Burden of Disease study. Newer estimates exist — behind login walls and restrictive terms. GBD 2019 is the newest openly published, country-complete table of firearm deaths from all causes (homicide, suicide and accidents together), so that is what we use, clearly labelled, until a newer open table appears. We check for one every year.

Pinning it has a side effect worth knowing: the GBD figures are age-standardized, which in an aging rich country runs below the raw rate — GBD 2019 puts the US at 10.1 firearm deaths per 100,000 while the CDC's crude figure for that era is around 12. Neither is wrong; they answer slightly different questions. It is exactly the kind of print-the-caveat situation our comparability grades exist for.

Laws aren't measured — they're read

Three of our snapshots aren't statistics at all. They are facts of law, compiled by reading statutes.

Paid vacation: every US state mandates zero days of paid annual leave, so any country with a statutory minimum outranks all fifty — that's not a data quirk, it's the honest comparison. The country figures require judgment calls a robot can't make: converting six-day-week entitlements (Germany's statutory 24 days become 20 five-day weeks) and calendar-day statutes into comparable working days.

Paid maternity leave: country figures come from the OECD's family database; the state side is a hand-checked list of which state programs actually pay benefits today — including the traps, like states that enacted programs which don't start paying for years.

State minimum wages: statutes change every January and July, so this file is reviewed twice a year. There's also a practical irony here: the US Department of Labor's own minimum-wage page blocks automated retrieval, so it gets re-verified by a human, by hand. We pull data from official APIs and published files only — when a source won't serve robots, the answer is manual checking, not scraping.

The annual review

Every snapshot lives in our repository next to a README recording what it contains, where each number came from, what conventions were applied, and what to re-check at review time: new PISA cycles, new EPI editions, newly-opened GBD tables, statute changes, program start dates. Each carries its retrieval date, and that date is shown on the sources page like any other.

Why not just auto-refresh everything?

Because an auto-refreshing pipeline pointed at edition-based or judgment-based data doesn't produce fresher data — it produces silent errors. A scraper misreads a redesigned page; a "new" file turns out to be a methodology change that breaks the series; a statute gets misparsed. Weekly automation is for sources that are built for it. For everything else, the honest configuration is: freeze a well-cited copy, show its date, and put a human review on the calendar.

The test we apply to every dataset is the same either way: could a reader trace this number back to its publisher and check it? For API data, that's a link and a refresh date. For snapshots, it's a citation, a retrieval date and a documented method. Both can be trustworthy. Only one should be automated.