world-geojson: country, state and area boundaries as a package

What the repository is

The repository contains GeoJSON data for the boundaries of all the countries, including boundaries for the states of the larger countries, and the readme notes in parentheses that the states are currently being filled in.

That parenthetical is the most useful sentence in the document, because it tells you the scope of the thing before you build on it. This is not a finished dataset of administrative boundaries for the world; it is a finished dataset of country boundaries, a good set of sub-national boundaries, and a work in progress for the rest.

The detail level is stated precisely: good for using the data at scales up to one in ten million, which is the equivalent of a zoom level six or seven in a web map, and the readme says it is the best quality available in combination with a free-to-use licence. So the positioning is a deliberate trade. A commercial boundary dataset would be more accurate and would cost money; this one is accurate enough for a world map, and the licence is free to use, which for an application that ships to customers is often the more important of the two properties.

The data is created with a web tool for drawing and exporting GeoJSON, which tells you something about the process: the boundaries were drawn or traced by hand, by people, in a tool that lets you see what you are doing. That is consistent with the rest of the readme, which talks about gluing borders together by hand and about replacing crowd-sourced outlines with handmade ones.

There is a quality example image near the top of the readme, which is the right way to let a reader judge the output before installing it, and the repository carries a banner in support of Ukraine at the very top, which says something about who maintains it and what they think matters.

The data is published under a copyleft licence, which for a dataset is a choice worth noting: a dataset is a derivative work of the geography rather than of anyone's expression, and requiring share alike on a boundary file is a stronger claim than the copyright law strictly requires.

Three levels, and the geography that makes them necessary

The structure of the dataset is a three-level hierarchy, and the release history explains how it was assembled.

The first release was the countries. The interesting decision there is what counts as a country: the boundaries besides the mainland include all the geographically separated but legally dependent, associated and managed territories. So the dataset is about de jure political entities, not about landmasses, and the mainland and the territories are separated into different files in the second release.

The second release added the areas: for the larger countries that are split into states, and for some smaller ones that are worth splitting geographically. And the list of what was split is the most interesting table in the readme, because it is a map of how awkward the world's administrative geography is.

France splits into eighteen: the mainland, Corsica, French Guiana, Guadeloupe, Martinique, Mayotte, Reunion, Clipperton Island, French Polynesia, New Caledonia, Saint Barthelemy, Saint Martin, Saint Pierre and Miquelon, Wallis and Futuna, and the French Southern and Atlantic Lands.

The United Kingdom into twenty-one, which includes the constituent countries as well as the crown dependencies and the overseas territories: the Isle of Man, Guernsey, Jersey, Gibraltar, the Sovereign Base Areas in Cyprus, Bermuda, the Turks and Caicos, the British Virgin Islands, Anguilla, the Cayman Islands, Montserrat, Pitcairn, Saint Helena with Ascension and Tristan da Cunha, the British Indian Ocean Territory, the Falkland Islands, and South Georgia with the South Sandwich Islands.

The United States into seventeen, which is the mainland plus the unincorporated territories: Palmyra Atoll, Guam, the Northern Marianas, Puerto Rico, the United States Virgin Islands, American Samoa, Baker Island, Howland Island, Jarvis Island, Johnston Atoll, Kingman Reef, Wake Island, Midway Atoll, Navassa Island, Serranilla Bank, and Bajo Nuevo Bank.

And then the countries that split three ways: Denmark into the mainland, Greenland and the Faroe Islands; Italy into the mainland, Sardinia and Sicily; Spain into the mainland, the Canaries and the Balearics; the Netherlands into seven; Norway into the mainland, Svalbard and Jan Mayen; Portugal into the mainland, the Azores and Madeira; New Zealand into twelve; Azerbaijan into the mainland and Nakhchivan; Ecuador into the mainland and the Galapagos.

So the hierarchy is not decorative. A dataset with only two levels could not represent France, the United Kingdom or the United States correctly, and the three-level model is the minimum that keeps the borders from overlapping or from implying a political relationship that does not exist.

Aligned borders, and the release that made the difference

The third release is the one that changed the dataset's usefulness, and its description is short: it is about gluing borders between all the countries so they perfectly align.

And the readme shows two images, one before and one after, which is the right way to present a change like this.

Why does it matter? Because a set of polygons that are individually correct can still render badly. If two neighbouring countries share a border but their coordinate sequences differ slightly, the renderer draws a visible seam, a hairline gap or an overlap along every internal border on the map. On a world map that is the difference between a drawing and a diagram. And the effect is not subtle: it appears along thousands of kilometres of border, and it appears in exactly the places where a viewer is looking, because people look at borders.

The fix is to make the shared vertices identical, which means editing the files by hand and by hand it must be, because a program cannot know that two boundaries are supposed to be the same curve. So the work is gluing, and the readme calls it that.

And then the fourth release extended the same treatment to the Australian states, and the fifth release was a different kind of change: region boundaries for Thailand and Switzerland, with an explicit warning that those region borders are not aligned with the country borders. Which is an honest admission that the alignment work is per pair and per level, and that adding a new level of subdivision to a country does not automatically give you aligned internal boundaries.

So the dataset has three states as far as alignment goes: country borders aligned with each other, Australian state borders aligned, and everything else approximately where it should be. A user who draws a choropleth over the dataset will get clean internal edges for the first case and visible seams for the second and third. That is a real limitation, and it is documented in the changelog rather than left to be discovered.

The JavaScript interface, and why it is synchronous

The usage section is short, and the Node.js part is the interesting half.

The readme notes first that the JSON files can be read from the directory in which the package was downloaded, and then that Node.js applications can use the provided helper functions to load the JSON synchronously as a JavaScript object.

So the package is a directory of files and a small set of functions, and the functions are synchronous.

That is an unusual choice in an ecosystem where everything is a promise, and it is worth understanding the reason. These are static files that ship with the package, not things fetched from a network, so an asynchronous read would buy nothing: the data is already on disk by the time the module is loaded. The only asynchronous work is reading each file when it is first asked for, and the design has decided that the simplicity of a direct return is worth more than the concurrency.

The three lookup functions are the same shape, one per level, and each returns the parsed contents of a file whose path is derived from the names you pass.

const geoJson = require('world-geojson') // or `import * as geoJson from 'world-geojson'`

geoJson.forCountry('Antigua & Barbuda'); // returns the contents of /countries/antigua_and_barbuda.json
geoJson.forState('Australia', 'New South Wales'); // returns the contents of /states/australia/new_south_wales.json
geoJson.forArea('U.S.A.', 'U.S. Virgin Islands'); // returns the contents of /areas/usa/us_virgin_islands.json

And there is a fourth, which is the one that makes the dataset usable for a choropleth. The combine function takes a list of objects, each naming a country, or a country and a state, or a country and an area, and merges them into a single set of features. So an application that wants to draw a map of a selection of administrative units asks for the selection in one call rather than merging polygons itself.

The installation section offers the same package through two ecosystems, one for the PHP side and one for the JavaScript side, with a version constraint on each, and it asks for help integrating it with other package managers. Which is the right thing to ask for from a data package: the more package managers can fetch it, the more likely it ends up in the dependency tree of something that needs boundaries and never thought about it.

The data quality record

The changelog in the readme is short, and reading it as a sequence is the best way to understand how the dataset is maintained.

Release 3.3 added Taiwan, and the entry is three words long: enough said, it was missing, now it is not.

Release 3.4 added the states of India, and the quality note under it is one line: quality is unknown.

The fifth release is a fix release, and its three bullets are the most informative lines in the document. It fixed the Taiwan border overlay. It added the missing Taiwanese islands. And it fixed a self-intersection in the Democratic Congo.

That last one is the interesting bug to have in a boundary dataset. A self-intersection is a polygon whose edge crosses itself, which is invalid as a shape and which makes rendering libraries do unpredictable things: some draw it, some refuse to draw it, some draw it with a bowtie across the middle. A border that crosses itself is a data error with a visible consequence, and the fact that the project tracked it down and fixed it in a patch release is a sign of the data being checked rather than merely collected.

So the record shows three kinds of entry. A feature that fills a hole, a feature whose quality is openly unknown, and a set of corrections to specific known problems. And the middle one matters most, because a project that says the quality of a national state layer is unknown is telling you exactly what you need to know before you draw it.

The release history also shows the cadence. The three most recent releases are minutes apart on the same day, which means the versions are being cut as the data is fixed rather than on a schedule. For a dataset that is assembled by hand, that is the natural rhythm, and the version numbers are there to tell a consumer whether their copy is current.

The one thing the readme does not claim is that the data is complete for states, and it says so in the summary at the top and again in the roadmap. The data quality record is thus incomplete by design, and the way to read it is as a list of what is known rather than as a list of what is right.

The roadmap, and the honesty about it

The planned work section opens with a paragraph that is unusual and, in a good way, blunt: there is no ongoing work right now and no commitment to have this ready within a certain timeframe, so these should not be counted on, but this is the plan in general.

That is a project declining to pretend, and for a dataset it is the right thing to say. A consumer who reads a roadmap with a version number and no dates will assume a delivery date. A consumer who reads this sentence will assume nothing, and will check.

The plan itself has two parts. The next release is about the two countries whose state borders matter most for the map: better Canadian province borders, glued borders for the provinces, better United States state borders, and glued borders for the states. So the alignment work continues where the demand is.

The one after that is the states, and the list of countries comes with a count of the states each one will have. Australia is ready. Canada is ready but the quality is low. The United States is ready from the crowd-sourced source. And the rest are pending with their counts: Argentina with twenty-four, Brazil with twenty-six, China with thirty-three, India with twenty-nine, Indonesia with thirty-four, Kazakhstan with fourteen, Mexico with thirty-one, the Philippines with eighteen, and Russia with eighty-three.

Those counts are the most useful thing in the list, because they are a workload estimate. Russia with eighty-three states is a country's worth of tracing that nobody has done, and seeing the number tells you how far away it is in a way that the word pending does not.

And the note about the source of the existing state borders is the honest part: some of them come from the crowd-sourced mapping data, whose quality is much lower, and they are eventually intended to be replaced by handmade ones. So the current state layer is a placeholder of the right shape with the wrong fidelity, and the project says so in the same document that lists the plans.

Which is the character of the whole repository. The country layer is done and aligned. The area layer is done where it matters. The state layer is a work in progress with an honest ledger. And the readme tells you which is which before you write a line of code against it.

Editorial conclusion

The dataset fits a mapping application that needs national and regional outlines without licensing a commercial provider, and fits a developer who wants the data in version control rather than fetched at run time. It does not fit an application that needs survey-grade precision, because the readme is explicit about the scale at which the detail is usable and about which parts are hand drawn and which come from a crowd-sourced source. Verify first which of the three levels your application needs: that the states are not complete, that the borders of the neighbours you use actually line up, since that is what the alignment releases fixed and not every region was included, and that you read the data quality record before shipping, because the project tracks its own known problems rather than hiding them.

Frequently asked questions

Official sources

1. georgique/world-geojson on GitHub
2. Issues
3. License: GPL-3.0
4. README
5. Releases