# Sources for `assets/data/countries.json` Generated by `scripts/build-countries.py` on 2026-09-12. Re-run that script to refresh the population and area figures; the names, capitals, aliases, continent assignments and notes are hand-curated inside it and are the part to edit by hand. ## The 195 The file contains exactly 195 states: the **193 UN member states** plus the **2 UN non-member permanent observer states**, marked `"un": "member"` and `"un": "observer"`. | What | Source | Checked | | --- | --- | --- | | The 193 member states | (the page renders one card per member state; 193 cards were parsed and every one matched an entry in this dataset) | 2026-09-12 | | The 2 observer states | (Holy See; State of Palestine, accorded non-member observer state status by GA resolution A/RES/67/19 on 29 November 2012) | 2026-09-12 | | Most recent admission | South Sudan, admitted 14 July 2011. The live UN list shows **no state admitted since**, so the total is still 193. | 2026-09-12 | Two details worth knowing, both confirmed against the live list: - The UN list now carries Nauru under its official name **Naoero**. It is recorded here as `Nauru` with `Naoero` as an accepted alias. - Kosovo, Taiwan, Western Sahara, the Cook Islands and Niue are **not** in this file. None is a UN member or a UN observer state. The `/explainers/how-many-countries/` page is the right place to explain why the count is argued about; the dataset itself takes one position and states it. ## Africa is 54 Africa contains exactly 54 states here, which is what the Africa quiz and `/explainers/how-many-countries-africa/` must both yield. The grouping follows the **UN M49 geoscheme** (), whose Africa region (Northern Africa 015 plus Sub-Saharan Africa 202) lists 54 countries and areas, all of which are sovereign UN members. The African Union has **55** members, because it also admits the Sahrawi Arab Democratic Republic (Western Sahara), which is not a UN member. Explainer pages should say 54 and then name that difference rather than dodge it. ## Continents `continent` is one of Africa, Asia, Europe, North America, South America, Oceania. It follows M49 with these deliberate calls, each of which also carries a `note` on the country entry so a page can surface the caveat: | State | Filed under | Why | | --- | --- | --- | | Russia | Europe | Transcontinental. M49 puts it in Eastern Europe, and the great majority of the population lives west of the Urals. | | Türkiye | Asia | M49 Western Asia. A small part, including part of Istanbul, is in Europe. | | Egypt | Africa | M49 Northern Africa. The Sinai Peninsula lies in Asia. | | Cyprus, Armenia, Georgia, Azerbaijan | Asia | M49 Western Asia, despite EU membership (Cyprus) and Council of Europe membership. | | Kazakhstan | Asia | M49 Central Asia. A western strip beyond the Ural River is usually counted as Europe. | Counts by continent: Africa 54, Asia 48, Europe 44, North America 23, South America 12, Oceania 14. ## Population - Field: `population`, with `population_source` and `population_year`. - Source for 194 of the 195: **World Bank, World Development Indicators, indicator `SP.POP.TOTL`**, most recent non-empty observation per economy, fetched from `https://api.worldbank.org/v2/country/all/indicator/SP.POP.TOTL`. Every value currently resolves to **2025**. The World Bank series is itself built on the UN World Population Prospects and national census data. - Palestine appears in the World Bank series as the economy **"West Bank and Gaza" (PSE)** and is used as the figure for the State of Palestine. - **Vatican City is not a World Bank economy.** Its figure (882, 2023) is the resident population of Vatican City State from the Holy See's *Annuario Pontificio*, as republished by the CIA World Factbook. Treat it as an order of magnitude, not a census: the Holy See does not publish an annual series and different sources give anything from roughly 500 to roughly 900. ## Area - Field: `area_km2`, with `area_source`. - Source for 194 of the 195: **World Bank `AG.SRF.TOTL.K2` (surface area, sq km)**, most recent non-empty observation (currently 2021 or 2023 depending on the country). Surface area is total area including inland water bodies, so these figures run slightly above "land area" figures quoted elsewhere. Pages that compare country sizes should say "total area". - Vatican City: 0.44 km2 (44 hectares), Vatican City State official government site, https://www.vaticanstate.va/en/state-and-government/general-informations/geography.html ## Capitals Hand-curated. Multi-seat and disputed cases are listed as an array, most significant first, and carry a `note`: Bolivia (Sucre, La Paz), South Africa (Pretoria, Cape Town, Bloemfontein), Sri Lanka (Sri Jayawardenepura Kotte, Colombo), Eswatini (Mbabane, Lobamba), Benin (Porto-Novo, Cotonou), Côte d'Ivoire (Yamoussoukro, Abidjan), Netherlands (Amsterdam, with the government at The Hague), Malaysia (Kuala Lumpur, with Putrajaya as the administrative centre), Tanzania (Dodoma), Burundi (Gitega), Palestine (Ramallah as administrative seat, East Jerusalem claimed; disputed), Israel (Jerusalem; disputed, most embassies are in Tel Aviv). A capitals quiz should accept any seat listed for a country as correct. ## Aliases `aliases` is the list of extra strings a quiz must accept in addition to `name`. It covers official long forms ("United States of America"), colloquial names ("America", "Britain", "Holland"), renames that are still in use ("Swaziland", "Burma", "Czech Republic", "Cape Verde", "East Timor", "Macedonia", "Turkey"), ASCII spellings of names carrying diacritics ("Cote d'Ivoire", "Turkiye", "Sao Tome and Principe"), and initialisms ("UK", "USA", "UAE", "DRC", "PNG", "DR Congo"). Matching in `assets/js/quiz-core.js` is accent- and punctuation-insensitive on top of this list, so the list does not need to carry every punctuation variant. ## Flags `assets/flags/.svg`, one per entry, vendored from the MIT-licensed [flag-icons](https://github.com/lipis/flag-icons) project (`flags/4x3/`) because the site's CSP sets `img-src 'self'`. Attribution and the upstream licence are in `assets/flags/LICENSE`. ## Not verified - Vatican City's population, as described above. - Area figures are the World Bank's most recent observation, which is two to four years old for some countries and will not match a live Wikipedia infobox to the square kilometre. - Alias lists are editorial judgement, not a sourced standard. Add to them when a quiz player reports a reasonable answer being rejected. ## Continent convention For the P2 North America page and anything else that counts by continent: `countries.json` assigns exactly one `continent` per country, and every state appears in exactly one of the six buckets. Counts, computed straight from the file on 2026-09-13: | Continent | Count | | --- | --- | | Africa | 54 | | Asia | 48 | | Europe | 44 | | North America | 23 | | South America | 12 | | Oceania | 14 | | **Total** | **195** | The named edge cases, all deliberate calls, not oversights: - **Russia** is filed under Europe, not Asia, despite most of its land area lying east of the Urals. - **Türkiye** is filed under Asia (M49 Western Asia), including the part of Istanbul that sits in Europe. - **Cyprus, Armenia, Georgia and Azerbaijan** are filed under Asia (M49 Western Asia), regardless of EU membership (Cyprus) or Council of Europe membership. - **Egypt** is filed under Africa (M49 Northern Africa), including the Sinai Peninsula, which is geographically in Asia. - **Panama and the Caribbean states** sit under North America, not a separate Caribbean or Central America continent. The 23 North America entries are Canada, the United States and Mexico; the six other Central American states plus Panama; and 13 Caribbean states (Antigua and Barbuda, the Bahamas, Barbados, Cuba, Dominica, the Dominican Republic, Grenada, Haiti, Jamaica, Saint Kitts and Nevis, Saint Lucia, Saint Vincent and the Grenadines, and Trinidad and Tobago). - **Kosovo and Taiwan are absent** from every continent count, along with Western Sahara, the Cook Islands and Niue, for the reason already given under **The 195**: none is a UN member or UN observer state. Read this file and these counts for any "how many countries in North America" or continent list claim. Do not hand type a number or a country list; render it from `countries.json`, the same rule section 8 of the P0/P1 build brief already sets for the site's pages. --- # Sources for `assets/data/compare.json` Built by `scripts/build-compare-data.py` for `/tools/country-comparison/` and `/compare/taiwan-vs-china/`. Rerun the script to refresh; do not hand edit the JSON, except that Taiwan's row lives in the script's `TAIWAN` table and is the one part of the file a human owns. ## The eight indicators All eight come from the **World Bank Indicators API v2** (), World Development Indicators database: | Key in the file | World Bank code | Indicator | | --- | --- | --- | | `gdp` | `NY.GDP.MKTP.CD` | GDP (current US$) | | `gdp_per_capita` | `NY.GDP.PCAP.CD` | GDP per capita (current US$) | | `life_expectancy` | `SP.DYN.LE00.IN` | Life expectancy at birth, total (years) | | `land_area` | `AG.LND.TOTL.K2` | Land area (sq km) | | `population` | `SP.POP.TOTL` | Population, total | | `urban_percent` | `SP.URB.TOTL.IN.ZS` | Urban population (% of total) | | `internet_percent` | `IT.NET.USER.ZS` | Individuals using the Internet (% of population) | | `military_percent` | `MS.MIL.XPND.GD.ZS` | Military expenditure (% of GDP) | Note that `land_area` (`AG.LND.TOTL.K2`) is **land area**, which is smaller than the **surface area** (`AG.SRF.TOTL.K2`) behind `area_km2` in `countries.json`: surface area includes inland water. The two figures will not match, and that is correct. Use `countries.json` for "how big is this country" and `compare.json` only inside the comparison pages, where the indicator is labelled. Military expenditure is the World Bank's redistribution of the **SIPRI Military Expenditure Database**; cite SIPRI where the page names a defence figure. ## Years are not uniform `mrv=N` on this API means the most recent N *periods*, not the most recent N non-null values per country, so a single most-recent-year request returns only the countries that have already reported: 10 of 195 for internet use. The script therefore requests a ten year window (`date=:`) and keeps, per country, the newest year that actually carries a value. Every value in the file is `{value, year}` and **the page must print the year.** Two countries in one comparison can be one or two years apart. (Recorded because it is a trap: on `country/all`, `mrv` is honoured on pages 2..n but collapses to `mrv=1` on page 1, which then reports `pages: 1` and ends any pagination loop that trusts it.) ## Coverage, build of 2026-09-13 Of the 195 states in `countries.json`: | Indicator | Covered | Missing | | --- | --- | --- | | GDP | 191 | Eritrea, North Korea, South Sudan, Vatican City | | GDP per capita | 191 | Eritrea, North Korea, South Sudan, Vatican City | | Life expectancy | 194 | Vatican City | | Land area | 194 | Vatican City | | Population | 194 | Vatican City | | Urban population | 194 | Vatican City | | Internet users | 191 | North Korea, Samoa, Vanuatu, Vatican City | | Military expenditure | 155 | 40 states, most of which have no standing army or do not report | Vatican City is absent from every World Bank series, as it is from the population series behind `countries.json`. A missing value must render as "no reported figure", never as 0 and never as an empty cell. ## Taiwan, the 196th key Taiwan reports to none of these series, and it is not one of the 195 states in `countries.json` (it is neither a UN member nor an observer). Because `/compare/taiwan-vs-china/` exists precisely to compare it, `compare.json` carries Taiwan as an extra key, `TW`, marked `"source": "manual"` and carrying `name`, `iso2`, `iso3` and a `note` of its own. **A country picker that offers Taiwan must read `compare.json`, not `countries.json`.** The 195 count does not move. Every Taiwan figure is cited individually, inside the row, with a `source`, a `url` and a `note`. Verified live on **2026-09-13**: | Indicator | Value | Year | Source | | --- | --- | --- | --- | | GDP | 920.05 bn US$ | 2025 | IMF World Economic Outlook, April 2026 (`NGDPD`), | | GDP per capita | 39,488.58 US$ | 2025 | IMF WEO April 2026 (`NGDPDPC`), | | Life expectancy | 81.27 years | 2025 | Ministry of the Interior, Abridged Life Table in Republic of China Area 2025, | | Land area | 36,197 sq km | not stated | Executive Yuan government portal, Geography, | | Population | 23,299,132 | 2025 | DGBAS / National Statistics, Total Population, | | Urban population | 78.92% | 2025 | UN DESA, World Urbanization Prospects 2025, national definitions, via Our World in Data | | Internet users | 88.75% | 2025 | TWNIC, Taiwan Internet Report 2025, | | Military expenditure | 2.10% of GDP | 2025 | SIPRI Military Expenditure Database, April 2026 | Four caveats a page must carry when it prints these: - **GDP comes from the IMF, not DGBAS.** DGBAS publishes real growth rates, not a US$ level; its own per capita announcement for 2025 (US$39,477) agrees with the IMF's 39,488.58 to within 0.03%, which is the corroboration. - **Land area has no reference year and the source says "around".** Print it without a year. - **Internet use is not the same definition** as the World Bank's row for every other country: TWNIC surveys adults aged 18 and over who used the internet in the previous three months. Say so where the Taiwan and China cells sit in one table. - **Urban share is secondary.** No Taiwanese agency publishes one, and the CIA World Factbook sunset in February 2026, so this is the UN national-definition estimate. Military spending is the one row that is directly comparable without a caveat: SIPRI is also the publisher behind the World Bank's `MS.MIL.XPND.GD.ZS`. Re-verify the whole table when DGBAS publishes its next annual figures. The values live in the `TAIWAN` table at the top of `scripts/build-compare-data.py`; edit them there and rerun, never in the JSON. - Monaco `area_km2` is overridden to 2.08 sq km (IMSEE, 208 hectares, including the Mareterra district opened December 2024; https://imsee.mc/en/thematics/territory-and-environment). The World Bank surface-area series reports 74.9 sq km for Monaco, which is anomalous. See `AREA_OVERRIDES` in scripts/build-countries.py. --- # Sources for `assets/data/us-states.json` Built on 2026-09-13 from live Census Bureau files. The file has two top level arrays: **`states`, which is exactly the 50 states**, and **`districts`, which holds one entry, Washington, D.C.** DC is deliberately not one of the 50 and a count of states must read `states` only. Both arrays are sorted by `name`, the file is ASCII only, and it carries no em dashes or en dashes. Per entry: `name`, `abbr` (USPS), `capital`, `largest_city`, `region`, `division`, `admitted`, `population`, `population_year`, `area_km2`, `aliases`. The DC entry adds `not_a_state`, `note` and `established`, and its `admitted` is `null`. | What | Source | Checked | | --- | --- | --- | | Population | Census Bureau Population Estimates Program, **Vintage 2025** state totals, `POPESTIMATE2025` (resident population as of 1 July 2025), | 2026-09-13 | | Region and division | The `REGION` and `DIVISION` codes in the same `NST-EST2025-ALLDATA.csv`, which is the Census Bureau's own coding of the scheme in | 2026-09-13 | | Area | Census Bureau **State Area Measurements**, the published *Total Area, Sq. Km.* column, | 2026-09-13 | | Capitals | USAGov (GSA) state directory, one page per state, and the other 49; the capital is the city in the governor's official *Main address* | 2026-09-13 | | Largest city | Census Bureau Population Estimates Program, **Vintage 2025** subcounty totals, `POPESTIMATE2025`, | 2026-09-13 | | Year of admission | Census Bureau, *U.S. Territory and Statehood Status by Decade, 1790 to 1960*, | 2026-09-13 | | DC establishment | Residence Act, signed 16 July 1790, Library of Congress research guide, | 2026-09-13 | ## Population `population_year` is **2025** for all 51 entries. Vintage 2025 is the newest vintage the Census Bureau has published; `POPESTIMATE2025` is the 1 July 2025 estimate, not a census count. The 2020 decennial count is in the same file as `ESTIMATESBASE2020` if a page ever needs to say "at the last census". The Census data API (`api.census.gov/data//pep/population`) now rejects keyless requests with a redirect to `missing_key.html`, so the flat CSV on `www2.census.gov` is the route to use and the one that was used here. ## Area `area_km2` is **total area, land plus water**, from the published *Total Area, Sq. Km.* column of the State Area Measurements table, whose measurements come from MAF/TIGER with boundaries as of 1 January 2010. This is the figure every general reference quotes (Alabama 135,767; California 423,967; Texas 695,662; Alaska 1,723,337). Summing `ALAND + AWATER` from the county gazetteer files was checked as an alternative and rejected. It agrees to within a few square kilometres for most states but diverges badly for coastal ones, because later TIGER vintages push more territorial water into coastal county boundaries: the 2026 county gazetteer sums Florida to 184,934 sq km against the published 170,312, a difference of about 14,600 sq km, almost all of it in Monroe County. Use the published column, and label the number "total area" on any page that prints it. ## Capitals All 50 were verified live, none by hand. USAGov publishes a page per state carrying the governor's office postal address, and the city on that address is the state capital in every case. Two spellings worth knowing: - Minnesota's capital is written **Saint Paul**, which is how USAGov and the state government write it. The Census place file writes the same city "St. Paul city". A capitals quiz should accept both. - Idaho's capital is **Boise**. The Census place file calls it "Boise City city"; the legal name of the place is Boise City and the city itself uses Boise. ## Largest city `largest_city` is the largest **incorporated place** (`SUMLEV` 162) or **consolidated city** (`SUMLEV` 170) in the state by the Vintage 2025 estimate. Where a consolidated city also has a "(balance)" place record for the same government, the balance record is dropped so the government is not counted twice: that affects Indianapolis, Louisville and Nashville. Census legal suffixes are stripped for display, so "Anchorage municipality" is stored as Anchorage and "Louisville/Jefferson County metro government" as Louisville. Seven entries surprise people and every one of them is correct: | State | Largest city | Note | | --- | --- | --- | | Alabama | Huntsville | 233,627, ahead of Mobile (200,824) and Birmingham (195,893). Huntsville passed Birmingham in 2021 and the gap is still widening. | | South Carolina | Charleston | 159,423, ahead of the capital Columbia (147,035). | | Virginia | Virginia Beach | 453,737, well ahead of Richmond (237,257). | | Missouri | Kansas City | 521,220, ahead of St. Louis (278,144). | | Nevada | Las Vegas | 679,817 for the city proper; most of the metro area lives outside the city limits, in Henderson, North Las Vegas and unincorporated Paradise and Spring Valley. | | Maine | Portland | 69,911, the smallest largest city of any state after Vermont's Burlington (44,019). | | Hawaii | Honolulu | **Hawaii has no incorporated places at all.** Honolulu is a census designated place, Urban Honolulu CDP, 341,868, inside the consolidated city and county of Honolulu. It is the one entry in this column that is not an incorporated place, because there is no such thing in Hawaii. | New York is stored as **New York City**, not the Census spelling "New York city", so the quiz string is unambiguous next to the state name. ## Aliases `aliases` is the list of extra strings a typing quiz must accept alongside `name`. The policy is deliberately narrow: - Every state carries **"State of X"** and its **USPS abbreviation**. - The four commonwealths also carry "Commonwealth of Massachusetts", "Commonwealth of Pennsylvania", "Commonwealth of Virginia" and "Commonwealth of Kentucky". - Washington carries **"Washington State"** and New York carries **"New York State"**, both of which the states themselves use to separate the state from, respectively, the federal capital and New York City. - Rhode Island carries **"Rhode Island and Providence Plantations"** and the long form of it, the state's name until the 2020 amendment. - **No nicknames and no slang.** No "Cali", no "Mass", no "Jersey", and no "Sunshine State" or any other state nickname. A nickname quiz, if one is ever built, needs its own field, not this one. DC carries "D.C.", "DC", "District of Columbia", "Washington DC", "Washington, DC" and "Washington District of Columbia". It does **not** carry bare "Washington", which is the state. ## Washington, D.C. DC sits in `districts`, not `states`, and carries `"not_a_state": true` plus a one sentence `note`. Its `admitted` is `null`, because it was never admitted; `established` is 1790, the year of the Residence Act. Census files do report DC in the South region and the South Atlantic division, and those values are kept on the entry, but DC is not included in the region and division counts below. Counts by region and division, computed straight from the file on 2026-09-13: | Region | Count | Divisions | | --- | --- | --- | | Northeast | 9 | New England 6, Middle Atlantic 3 | | Midwest | 12 | East North Central 5, West North Central 7 | | South | 16 | South Atlantic 8, East South Central 4, West South Central 4 | | West | 13 | Mountain 8, Pacific 5 | | **Total** | **50** | | ## Not verified - Nothing in the file is hand typed from memory. Every figure came off a live Census Bureau or USAGov URL on 2026-09-13. - `area_km2` is a 2010 boundary vintage, which is the newest the published state area table offers. It will not match a gazetteer sum for coastal states, for the reason set out under **Area**. - `largest_city` moves. Huntsville over Birmingham and Charleston over Columbia are both recent flips; recheck this column when the next vintage lands, usually in the following May.