country-codes puts every ISO 3166-1 entry and its neighbours in one CSV

One row per country, with the columns you would otherwise assemble by hand

The dataset is a single CSV, `data/country-codes.csv`, with one row per country or territory that has an ISO 3166-1 entry. What it joins is the part that saves work. The ISO 3166 alpha-2, alpha-3 and numeric codes come first, and then the other code systems: ITU, FIPS, IOC, FIFA, WMO and more. Alongside them sit telephone dialling codes, the ISO 4217 currency codes, the UN M49 region groupings, country names in six languages, and identifiers from GeoNames, the SEC's EDGAR system and Wikidata. The alpha-2 and alpha-3 columns are each unique, so they work as join keys against your own tables. The file is published as a Tabular Data Package, with the column definitions and types in `datapackage.yml`, which means a tool that understands that specification can read the types instead of guessing them. Rows are sorted by `official_name_en`, but the sort order comes from the machine that builds the file, so a few names can change places between builds, which is a small reminder that a generated dataset has a build order as well as a schema.

NA is real data, and pandas will turn it into a hole

The first known limitation is the one that will bite first. The continent code for North America is `NA`, the alpha-2 code of Namibia is `NA`, and the `DS` value for Bonaire, Sint Eustatius and Saba is also `NA`. `pandas.read_csv` converts `NA` into a missing value by default, so those cells come back empty and the data looks like a gap where there is a legitimate code. The fix is to read everything as text and switch off the default NA handling:

import pandas as pd
df = pd.read_csv("data/country-codes.csv", dtype=str, keep_default_na=False)

Reading as text is the right default for this file in general, because several numeric columns are stored as numbers with their formatting stripped, and because a postal code, a currency numeric code and a region code are identifiers rather than quantities. The same instinct applies to the currency numeric code, which keeps its leading zeros, for example `008`, and is therefore expected to arrive as a string.

The numeric codes have lost their leading zeros

Three numeric columns are stored as plain numbers: `ISO3166-1-numeric`, `M49` and the UN region codes. The documentation uses Afghanistan as the example, where ISO writes `004` and the file holds `4`. That is not a rounding error, it is a change in the identifier, and a system that stores these as integers cannot tell `4` from `004` once the value has been through a database column. The three digit form is one call away:

df["ISO3166-1-numeric"] = df["ISO3166-1-numeric"].str.zfill(3)

The same treatment is needed for the M49 and UN region columns, and it is worth deciding at the start of a project which representation you store, because re-padding later means re-reading the file or migrating every row you already have. Note that `ISO4217-currency_numeric_code` is the exception: it keeps its leading zeros, for example `008`, so it should be read as text and left alone.

Empty cells that are not empty, and cells holding several values

Two more parsing traps are documented, and they pull in opposite directions. Where Statoids has no code, the cell holds a single non-breaking space, U+00A0, rather than nothing. That happens in the `FIFA`, `Dial`, `MARC`, `FIPS`, `WMO`, `ITU`, `IOC` and `DS` columns, and a few other cells, `Capital` for instance, carry stray spaces. A naive emptiness check therefore reports data where there is none. The documented fix strips after reading:

df = df.apply(lambda col: col.str.strip())

Then there are cells that hold several values separated by commas. The `Dial` column for the Dominican Republic is `1-809,1-829,1-849`, the `Languages` column lists several language codes, and a country with two currencies has two values in each `ISO4217-currency_*` column in the same order, so `BT` carries `INR,BTN` and `356,064`. Separating them is a `.str.split(",")` call, but the ordering rule is what makes that safe to do rather than a guess.

A licence column, because the sources do not share terms

The documentation includes a table of data sources, and the last column of it is the interesting one: it records what was found about reuse for each source. The UN Protocol and Liaison Service names are marked restricted, because the UN terms of use allow downloading and copying for personal, non-commercial use, without any right to resell or redistribute them or to compile derivative works, and no separate licence was found for the file. The M49 page states no licence, and the same UN terms probably apply but could not be confirmed. Statoids, the SIX Group currency list and the FIFA member associations pages are all recorded as unclear for the same reason. The ISO codes themselves are marked unclear, because ISO allows free of charge use of its country, currency and language codes while also stating that any use, including reproduction, requires written permission. GeoNames is the clean case, under CC BY 4.0, with credit required, which is why the repository ships an `ATTRIBUTION.txt`. The practical consequence is that the file as a whole has no single licence, and the columns you use decide what you may do with them.

The build is a chain of scripts joined on the alpha codes

The Makefile shows how the file is assembled, and it is a pipeline rather than a script. The default target runs the validation, which is a single command:

frictionless validate datapackage.yml

The data target then walks a dependency graph. A custom `scripts/iso3166.py` produces the ISO data, `scripts/iso4217.py` and `scripts/format_json.py` add the currency codes, `scripts/statoids.py` adds the code systems, and `scripts/flatten.py` produces a flat JSON file. The auxiliary tables are built in parallel by `scripts/geoname.py`, `scripts/edgar.py`, `scripts/cldr.py` and `scripts/unterm_names.py`, and the final CSV is produced by `in2csv` and then joined with the `csvjoin` utility, once on the alpha-3 code to attach GeoNames, once on the alpha-2 code to attach CLDR, and once on the currency country name to attach EDGAR. A `diff` target compares the result against `previous-country-codes.csv` with `daff` and renders an HTML diff, which is how a change to the data is reviewed before it lands.

What the file does not contain, and the gaps to code around

The limitations list is worth reading as a specification of the data's edges. Only ISO 3166-1 entries have a row, so Kosovo, coded `XK` elsewhere, has none. The `UNTERM` name columns are empty for many territories and for some countries, with `AQ`, `HK` and `CI` given as examples. The `EDGAR` column is matched by country name, so it is empty wherever the SEC's name differs from the one used here, which the documentation names as `CA` and `US`. The region columns are empty for Antarctica. The optional UN groupings for least developed countries, land locked developing countries and small island developing states are empty unless the country belongs to that group. A few `FIFA` values are not three letter codes at all, `1` for `GB` and `ROS3` for `AQ`, because the pipeline leaves a value alone when neither it nor the country's alpha-3 code appears on the FIFA list. And `wikidata_id` is a full URL, for example `https://www.wikidata.org/wiki/Q889`, not the bare `Q` number. The repository itself lists no licence file, so the column level terms in the documentation are the only licensing information available.

Editorial conclusion

country-codes suits anyone building a country picker, a currency table or a phone number normaliser who wants one download instead of five, and it suits teams that care about provenance, since the source table states the licence of every column and the repository ships an attribution file. It does not suit a project that needs a single authoritative source per field, because several columns are merged from sources with unclear or restricted terms, and it does not suit code that expects country codes to be a closed set, since only ISO 3166-1 entries have a row. Before you depend on the file, check three things: that you read it as text with default NA handling turned off, that the columns you use are the ones whose licence permits your use, and the row count against your own expectations, with the last push to the repository on 2026-10-15 and no tagged releases to pin a specific build to.

Frequently asked questions

Official sources

1. datasets/country-codes on GitHub
2. Issues
3. Project website
4. README