geo-countries: every country border as one GeoJSON file

One FeatureCollection, three properties, nothing else

The datasets/geo-countries package is a GeoJSON file of country polygons. The README describes it as GeoJSON polygons for the world's countries and for some territories, disputed areas and special areas, taken from Natural Earth, where each polygon carries the country name and its ISO 3166-1 alpha-2 and alpha-3 codes.

The data itself is a single file, `data/countries.geojson`, holding one GeoJSON `FeatureCollection`. Each feature is one country or area, expressed as a `Polygon` or a `MultiPolygon`, and carries three properties. `name` is the common name, for example `Argentina` or `Kosovo`. `ISO3166-1-Alpha-3` is the three letter code, for example `ARG`. `ISO3166-1-Alpha-2` is the two letter code, for example `AR`.

That is the whole schema, and the column definitions and types live in `datapackage.json` rather than in prose, which is the right place for them. A data package describes the resource in a machine readable way, so a consumer can pick up the file and its metadata together.

For richer country attributes, the README points to the separate country-codes data package and says to join it on `ISO3166-1-Alpha-3`. That join key is the one detail in this file that needs care, and the README is unusually candid about why.

The repository is MIT licensed for the source code, and the primary language recorded for the project is Makefile, which tells you the shape of the thing: there is no application, only a build recipe.

The -99 placeholder and why a join silently loses rows

Natural Earth writes `-99` where it has no ISO code in its main code fields. The build fills the gap for the two real countries affected, France and Norway, using Natural Earth's own `ISO_A2_EH` and `ISO_A3_EH` fields, giving `FRA` and `FR` for France and `NOR` and `NO` for Norway. The Makefile encodes exactly that rule in a SQL statement inside the ogr2ogr call, so the fix is applied during the conversion rather than patched afterwards.

Some features still carry `-99` in both code fields, and the README lists them: Kosovo, Northern Cyprus, Somaliland, Siachen Glacier, Spratly Islands and Clipperton Island. These are disputed or special areas with no ISO 3166-1 code at all.

The consequence is stated without euphemism. A join on `ISO3166-1-Alpha-3` will not match those features, and `-99` is not a unique key because it appears on every one of them. So a naive join against any ISO keyed table loses the disputed areas entirely, and a naive grouping by that column collapses six distinct places into one bucket. If your application needs them, they have to be handled by name, by geometry, or by an explicit exclusion list.

This is the kind of limitation that is usually buried in a data package's issue tracker. Here it is in the README, under a heading called Known limitations, which is the difference between a trap and a documented edge case.

Rebuilding the file with GDAL and ogr2ogr

The build needs `make`, `curl` and GDAL, for the `ogr2ogr` tool. To confirm GDAL is installed, the README gives a single check:

ogr2ogr --version

To rebuild `data/countries.geojson`, the command is:

make data

That target downloads the latest 10m Admin-0 Countries file Natural Earth publishes into `ne_10m_admin_0_countries.zip`, converts it with `ogr2ogr` and writes `data/countries.geojson`. The version is not pinned, which is a deliberate choice and the single most important thing to understand about the build: a rebuild months from now can produce different geometry if Natural Earth has revised the source.

The conversion does several things at once. It keeps only the three properties described earlier, rounds coordinates to at most 6 decimal places, and repairs invalid geometries with `-makevalid`, for example self-intersecting polygons. The Makefile also sets the coordinate precision explicitly and selects the SQLite dialect so that the CASE expressions can run against the shapefile attributes.

If the zip file is already present it is reused rather than downloaded again, and the clean target removes it. Run `make clean` to delete the downloaded archive, which is also how you force a fresh download on the next build.

A monthly rebuild committed back to the repository

The automation around the build is simple and worth noting. A GitHub Actions workflow runs `make data` on the first of every month, and also on pushes to `main` and on manual runs, and commits `data/countries.geojson` if it changed.

So the file in the repository is the artefact, not a build output you are expected to produce. The commit history is a changelog of how Natural Earth's boundaries have moved, and the monthly schedule means the data you get from a fresh clone is at most a month behind the source.

The repository is not archived, the last push was on 2026-10-15, and there are no GitHub releases, which is consistent with a project where the versioned artefact is the file in the tree rather than a tagged archive. The homepage is the Datahub core page for geo-countries, which is where the package is presented to people who did not arrive from Git.

One consequence of the automated rebuild is worth thinking about before you pin anything. Because the build is not pinned to a Natural Earth version and the workflow runs on every push to main, the content of the file on main can change without a version bump of its own. If your pipeline needs a stable boundary definition, copy the file into your own repository at a known commit rather than tracking main.

Ring direction, RFC 7946 and the shape of the geometry

There is a specification detail in the known limitations that affects how the file behaves in strict tools. The outer rings of the polygons run clockwise. The build does not change ring direction. RFC 7946 asks for counter-clockwise rings, but most tools accept both.

That is an honest trade-off: the build preserves whatever Natural Earth produced rather than rewriting the winding order of every polygon, and the consequence is that a validator which enforces the RFC strictly will complain, while the common mapping and GIS libraries will not care.

Coordinates have at most 6 decimal places, which is a rounding decision made during the ogr2ogr conversion. Roughly a tenth of a metre at the equator, and far less in practice for country outlines, so it is a reasonable trade for file size and it removes spurious precision from what is ultimately a public domain reference layer.

The other documented behaviour concerns political meaning rather than geometry. Natural Earth draws country boundaries according to its de facto status, following its own disputed boundaries policy, and the README states plainly that these are not necessarily the borders that any one government claims. The data package includes disputed areas and special areas as first class features, which is the more useful behaviour for most applications: you get the areas as they are, and the decision about how to label them stays with you.

Two licences, and a different way to get the data

The licensing is the part of this project that needs the most careful reading, because there are two of them and they cover different things.

The geometry and the three properties come from Natural Earth, whose terms of use put the data in the public domain and allow commercial use without permission or credit. The README also notes that the maintainers found nothing in the file that Natural Earth credits to another provider, since the three properties are Natural Earth's own country name and ISO code fields.

The maintainers offer the package itself under the Open Data Commons Public Domain Dedication and License, PDDL, version 1.0. A credit is not required, but a link back to Natural Earth, to Lexman and to the Open Knowledge Foundation is appreciated, and the repository carries an ATTRIBUTION.txt file with those details. All source code is licensed under the MIT licence.

So a commercial product can use the geometry without asking permission, and the MIT licence covers the build recipe. What you should not do is present the boundary data as a statement of what borders a country are, because the de facto status caveat travels with the data.

The alternative to building this yourself is straightforward: go to the Natural Earth download page for the 10m Admin-0 Countries layer and read the shapefile directly. The difference in approach is what this package adds and what it decides for you. Natural Earth gives you more attributes than you probably need, in a format that needs a conversion step. This package gives you one GeoJSON file with three properties, invalid geometry repaired, coordinates rounded, and the France and Norway code problem already solved. If you need the other Natural Earth fields, you need the upstream file anyway, and this package becomes a convenience layer rather than a source.

Editorial conclusion

Adopt geo-countries when you need a country boundary layer for maps, charts or validation and you want the geometry already converted, repaired and keyed by ISO code rather than assembling it yourself from Natural Earth. Do not adopt it as a source of administrative truth, because the boundaries follow Natural Earth's de facto status and several disputed areas carry no ISO code at all, and do not use ISO3166-1-Alpha-3 as a join key without handling the -99 rows. Before you build on it, run ogr2ogr --version to confirm GDAL is present, read the known limitations section, and decide how you will key the Kosovo, Northern Cyprus, Somaliland, Siachen Glacier, Spratly Islands and Clipperton Island features that share the -99 placeholder.

Frequently asked questions

Official sources

1. datasets/geo-countries on GitHub
2. Issues
3. License: MIT
4. Project website
5. README