WorldHUD › Data API
Data API
The numbers WorldHUD shows, as plain files: 48 stats for 239 countries and territories, a leaderboard for each stat and the Level board, each value with its year, its source and its licence. Free, with no sign-up. Built from the data snapshot of 2026-11-15 by the same code as the app.
What it is
The HUD's own numbers as files, under https://worldhud.io/api/v1/: JSON, CSV for the tables and GeoJSON for the places. Every stat value is the newest one its source published by the snapshot, with its own year; ranks, ties, "no recent data", per person, attributes and Levels are computed by the same rules as the app (Method & sources). The files change only when the snapshot does.
Quick start
curl -s https://worldhud.io/api/v1/places/SWE.json
curl -s https://worldhud.io/api/v1/boards/energy.elec_gen.csv
curl -s https://worldhud.io/api/v1/stats.jsonThe first lines of places/SWE.json, as built:
{
"api": "v1",
"generated": "2026-11-15",
"docs": "https://worldhud.io/api/",
"terms": "https://worldhud.io/api/#terms",
"attribution": "Each value names its source and licence (source.name, source.url, source.licence): keep them with the value when you pass it on, as each licence requires. Share-alike material keeps its share-alike terms.",
"data": {
"place": {
"iso3": "SWE",
"iso2": "SE",
"name": "Sweden",
"slug": "sweden",
"region": "Europe",
"subregion": "Northern Europe",
"player": true,
"population": {
"value": 10597000,
"year": 2025,
"source": {
"name": "World Bank WDI",
"agency": "UN (World Population Prospects); National statistical offices; Eurostat; UN (Population and Vital Statistics Report)",
"url": "https://data.worldbank.org/indicator/SP.POP.TOTL",
"licence": "CC BY 4.0",
"retrieved": "2026-11-12"
}
},
"links": {
"sheet": "places/SWE.json",
"page": "https://worldhud.io/country/sweden/",
"app": "https://worldhud.io/#/country/SWE"
…Files
All under https://worldhud.io/api/v1/. {ISO3} is the place's three-letter code; {stat} is a stat id as stats.json names its file (the id in lower case, any character other than a letter, a digit, ".", "_" or "-" made "-"; energy.solar stays energy.solar).
| Path | What | Rows |
|---|---|---|
index.json | Every file with its rows | 343 files |
stats.json | The stats catalogue: unit, direction, newest year, places ranked, full provenance | 48 |
places.json | Every place: codes, name, slug, region, population, Level, rank, rank range, class, attributes, 10-year progress, badges | 239 |
places.csv | The same places, one flat row each | 239 |
places.geojson | The globe's 177 shapes and 65 places with no shape as points, with Level, attributes and class | 242 features |
places/{ISO3}.json | One place's sheet: every stat it reports at its newest value, with its rank, per person where there is one, and its source | 239 files |
boards/{stat}.json | One board, in rank order, then the places with no recent data; "level" is the Level board | 49 files |
boards/{stat}.csv | The same boards as CSV; every row names its year, source and licence | 49 files |
openapi.json | This API described as OpenAPI 3.1 |
Fields
- Every JSON file has the same envelope:
api("v1"),generated(the snapshot date),docs,terms,attributionanddata. A GeoJSON file carries the same fields beside its features. - The source rule. Every value that comes from a source has its
yearand asourcebeside it:name,agency(who produced it),url(the indicator at the source),licence, andretrievedwhere the snapshot has it. A filled value (the stat's own source does not report the place) names the fill's source, withfilled: true. In CSV every row carriesyear,source_name,source_urlandlicence, so a row cut out of the file still names its source. - Computed. The Level, attributes, class, ranks, badges, rank range and per-person figures are WorldHUD's own: their block has
computed: trueand amethodlink, and no source. - Missing is null. A missing value is
null(or an empty CSV cell), never 0. A place with no Level haslevel: null. - Ranks. Ties share the best rank; tied is how many share it. A value more than 5 years behind the stat's newest year has noRecentData: true and no rank (on a board it is listed under noRecentData). Where the source publishes a floor, a value at or below it has atFloor: true, ties at the floor and displays as the source prints it ("<2.5 %").
- Per person. On volume stats, perPerson is the value divided by the population of the value's own year; places under 250,000 people are not ranked per person.
- Projections. UN projection: UN World Population Prospects 2024 estimates population up to 2023; its figures for later years are its medium-variant projection. A population that is one has projection: true, and so has a per-person figure divided by one; in CSV that is population_projection (places.csv) and projection (boards/pop.total.csv).
- Level. A Level needs 4 of the 6 attributes; one built on fewer says so in levelText ("LV 73 · 5/6"). rankRange is the Level rank under three readings: as published, per person only, size only. The current Level is built from each stat's newest value that is recent enough to rank, so it mixes years and has no single year. In CSV its year cell is empty and basis reads "newest values". progress10y.levelFrom and levelTo are the Level as of the years from and to, by the as-of rule: each stat at its newest value in or before that year, recent enough relative to it. The current Level is built from each stat's newest value, so the two can differ, even for the data year.
Attribution
When you pass a value on, pass on its source and licence with it. Each licence says what credit it needs; under CC BY, that is the source's name and a link to the licence. The sources and licences in this snapshot:
| Source | Licence | For |
|---|---|---|
| Our World in Data – CO₂ | CC BY 4.0 (third-party data keeps its original licence) | CO₂ emissions, CO₂ per person |
| Our World in Data – Energy | CC BY 4.0 (third-party data keeps its original licence) | Electricity generated, Electricity per person, Renewable electricity, Low-carbon electricity, Solar power, Wind power, Nuclear power, Hydro power, Oil production, Gas production, Coal production, Energy use per person, filled values of Population |
| Our World in Data – Life expectancy at birth | CC BY 3.0 IGO | filled values of Life expectancy |
| Paris 2024 medal table (Wikipedia) | CC BY-SA 4.0 (Wikipedia text; the medal counts are facts published by the IOC) | Paris 2024 medals, Paris 2024 golds |
| World Bank WDI | CC BY 4.0 | Cereal production, Cereal yield, Farm, forest and fishing output, Farm output per worker, Arable land per person, Agricultural land, Agriculture share of GDP, Undernourishment, Life expectancy, Infant mortality, Health spending per person, GDP, GDP per person, GDP growth, Exports, Unemployment, Electricity access, Internet users, Mobile subscriptions, Air passengers, Safe drinking water, Forest cover, Protected land, Land area, R&D spending, University enrolment, Patent applications, High-tech exports, Population, Urban population, Population growth, Fertility rate |
Share-alike. Paris 2024 medals and Paris 2024 golds: Paris 2024 medal table (Wikipedia), CC BY-SA 4.0 (Wikipedia text; the medal counts are facts published by the IOC). Whatever you make from these values must carry the same licence.
The shapes in places.geojson are from Natural Earth 1:110m (world-atlas): public domain. A place drawn as a point sits at the coordinates world.json records; each feature names their source.
Something missing?
If you need something these files do not have, such as a longer history, another format or another stat, write to hello@worldhud.io.
Not in the API
- Live events and alerts: they are the issuing agencies' own, copied every few minutes into one file the site reads; several of the ten providers state no licence for reuse, and an alert is only worth having from its issuer. The site lists each provider and its terms under Method & sources.
- People (Most looked-up): a ranking of named people is not offered as data.
- City lights: GeoNames' own file again; take it from GeoNames.
- Field notes: Wikidata's own statements again; take them from Wikidata.
Terms
Draft of 2026-11-15.
- WorldHUD is operated by Katame Games, LLC.
- Do not rely on WorldHUD for navigation, in an emergency, or for any decision where safety is at stake.
- The API is provided as it is, with no warranty of any kind. There is no promise that it will be available, or that a request will be answered within any time.
- The numbers are the sources' own. They can be wrong, revised or late.
- When you pass a value on, keep its source and its licence with it.
- WorldHUD is not affiliated with or endorsed by any of the sources.
- The Level, the attributes and the ranks are WorldHUD's own method: see Method & sources.
- The API is free, and it is offered without liability of any kind, to the extent the law allows.
- These terms may change with the data snapshot.