geoBoundaries

Built by the community and William & Mary geoLab, the geoBoundaries Global Database of Political Administrative Boundaries Database is an online, open license (CC BY 4.0 / ODbL) resource of information on administrative boundaries (i.e., state, county) for every country in the world. Since 2016, we have tracked approximately 1 million boundaries within over 200 entities, including all UN member states. All boundaries are available to view or download in common file formats; the only requirement for use is acknowledgement.

Related Repositories

The geoBoundaries project is made up of a number of different repositories; you are currently on the core repo which stores all input datasets and builds. If you are interested in understanding other components of geoBoundaries, you can visit:

• geoBoundaryBot: where our build scripts live, as well as the various QA/QC algorithms applied to pull requests in this repository. If you're interested in the specifics of our topology checks or simplification strategies, this is where to look.
• gbWeb: where the website itself lives, as well as the API. Various scripts that aid in building the API and other things related to the website can be found here as well.
• rgeoboundaries: built by community member @dickoa, this library allows you to retrieve and manipulate geoBoundaries data within the R programming environment.
• pygeoboundaries built by community member @ibhalin, this package allows you to retrieve and manipulate geoBoundaries data within the python programming environment.

Getting Involved

We welcome contributions to the geoBoundaries dataset. Involvement can take many forms: assistance identifying errors in the database, contributing boundary files, or even contributing code for our build or website scripts. To get started, you could:

• Report Boundary Errors: While we try to ensure geoBoundaries is as error-free as possible, we are currently tracking around 300 million vertices across hundreds-of-thousands of geometries - there are bound to be issues! We very much welcome any reports of errors across the database.
• Contribute Boundaries: We carefully curate all boundaries that are submitted to the database, and have a very active community. Join us in the fun! We try to keep things simple for everyone, requiring only a zipfile upload.
• Fix Known Issues: We have a number of known issues with the database, and always welcome contributions that might fix any of these.
• Help with the Python Code: We always welcome contributions to our codebase that improve the efficiency of our processing, or introduce new types of checks to automatically prevent errors. Our code includes a number of different pieces, such as the www.geoboundaries.org website, API, the geoBoundaryBot (responds to PRs), and our formal build scripts.

File Access

We provide three different mechanisms to download geoBoundaries data: a web-based GUI, HTML file access on GitHub (for archival versions), and an API. Releases come in both unsimplified and simplified types, and include a global composite of ADM0, ADM1, and ADM2 with gaps filled between borders ("CGAZ"). Acronyms describing these datasets you may encounter include:

HPSC - High Precision Single Country. The premier geoBoundaries release, representing the highest precision files available for every country in the world. Every country is represented as that country represents itself, so (for example) two countries may overlap in the case of contested boundaries.

SSC - Simplified Single Country. A simplified version of every file available for every country in the world, using the HPSCU product as a base.

CGAZ - Comprehensive Global Administrative Zones. A global composite of the SSC ADM0, ADM1 and ADM2, clipped to international boundaries (US Department of State), with gaps filled between borders. Also available at higher levels of simplification.

Versioned Releases for Research Replication

While geoBoundaries is always updating, we provide annual releases to facilitate future research replication. To download a file from any release, you can navigate to our releases page, and choose the release you are interested in retrieving files from, or you can navigate to the appropriate location using this table:

If you are interested in releases prior to 1.3.4, please contact us.

Programmatic / API Access

Full details on our API are available here.

To find information on the most up-to-date boundaries available-

https://www.geoboundaries.org/api/current/gbOpen/[3-LETTER-ISO-CODE]/[ADM-LEVEL]/

Users can also enter the special phrase "ALL" for either "ADM" or "ISO" to get a multi-boundary return. Each requested boundary returns all metadata available for that boundary in the gBOpen release, including a link to both the full-resolution, large-file size and the simplified small-file size versions. Users can additionally replace "gbOpen" with either "gbAuthoritative" or "gbHumanitarian" to filter results to only include boundaries from those two respective releases.

Of note, to facilitate speed of queries against the API all JSONs are pre-cached and can be exported in bulk by cloning the geoBoundaries Website repository for local use.

Note on Cloning

As of geoBoundaries 5.0.0, all files in geoBoundaries are stored using Git's Large File Storage (LFS). Because this entails such a large volume of files, a bug in the current GitHub API results in a rate limiting error if you attempt to clone using https methods (i.e., git clone https://github.com/wmgeolab/geoBoundaries.git will fail with a rate limiting error). Cloning with SSH (git clone [email protected]:wmgeolab/geoBoundaries.git) and the GitHub CLI (gh repo clone wmgeolab/geoBoundaries) work without issue.