API & Archival Access
Web-based Archival Access
Since geoBoundaries 3.0, file access has been standardized on the github platform. 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. Our first public release, geoBoundaries 2.0, is available online through the Harvard Dataverse.
API Access to geoBoundaries
NOTE: The legacy geoBoundaries API (located at https://www.geoboundaries.org/gbRequest.html) will be deprecated with the release of geoBoundaries 5.0, which is expected to be in or around May of 2022.Information on every geoBoundary - current and past - can be retrieved through a simple query; a JSON object is returned. We provide two endpoints for users.
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-LEVEL]" or "[3-LETTER-ISO-CODE]" 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 minor simplification (~5%), small-file size versions. In cases where a gbHumanitarian or gbAuthoritative release is available for a boundary, that information is provided in sub-objects within the returned json. Users can additionally replace "gbOpen" with either "gbAuthoritative" or "gbHumanitarian" to filter results to only include boundaries from those two respective releases. Finally, "current" can be replaced with a major version to retrieve information specific to that major release (e.g., "v4" will provide the IDs of v4 boundaries, which can be used with the below historic API to retrieve the boundary metadata for a specific version).
To find information on any geoBoundary, past or present, based on the geoBoundary ID:https://www.geoboundaries.org/api/gbID/[geoBoundaryID]/
Starting with the geoBoundaries 4.0 release, all geoBoundaries can be referenced by ID using the above API.
The returned elements are identical to those in the /current/ API endpoint.
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.
import json import requests r = requests.get("https://www.geoboundaries.org/gbRequest.html?ISO=EGY&ADM=ADM1") dlPath = r.json()[0]['gjDownloadURL'] geoBoundary = requests.get(dlPath).json() print(geoBoundary["features"][1]["geometry"])
{'coordinates': [[[ [34.52329565, 27.966960461223056], [34.5237859, 27.9668325], ... ]]], 'type': 'MultiPolygon'}
import json import requests from matplotlib import pyplot as plt r = requests.get("https://www.geoboundaries.org/gbRequest.html?ISO=EGY&ADM=ADM1") dlPath = r.json()[0]['gjDownloadURL'] geoBoundary = requests.get(dlPath).json() #Matplotlib Visualization fig = plt.figure(1, figsize=(5,5), dpi=90) axs = fig.add_subplot(111) axs.set_title('Example Visualization') #Accounting for Multipolygon Boundaries for boundary in geoBoundary["features"]: if boundary["geometry"]['type'] == "MultiPolygon": polys = boundary["geometry"]["coordinates"] for poly in polys: exterior = poly[0] xs, ys = zip(*exterior) axs.fill(xs, ys, alpha=0.5, fc='red', ec='black') else: exterior = boundary["geometry"]["coordinates"][0] xs, ys = zip(*exterior) axs.fill(xs, ys, alpha=0.5, fc='red', ec='black') fig.savefig("example.png")

Generic Query Example:
https://www.geoboundaries.org/gbRequest.html?ISO=USA&ADM=ADM1&TYP=SSCU&VER=3_0_0
Response Example:
[ { "boundaryID": "USA-ADM1-3_0_0-G618", "boundaryISO": "USA", "boundaryYear": "2017.0", "boundaryType": "ADM1", "boundarySource-1": "US Census", "boundarySource-2": "", "boundaryLicense": "Open Data Commons Open Database License 1.0", "licenseDetail": "", "licenseSource": "https:\/\/www.census.gov\/about\/policies\/open-gov\/open-data.html", "boundarySourceURL": "https:\/\/www.census.gov\/geographies\/mapping-files\/time-series\/geo\/carto-boundary-file.html", "boundaryUpdate": "2020-05-25", "downloadURL": "https:\/\/geoboundaries.org\/data\/geoBoundariesSSCU-3_0_0\/USA\/ADM1\/geoBoundariesSSCU-3_0_0-USA-ADM1-all.zip", "gjDownloadURL": "https:\/\/geoboundaries.org\/data\/geoBoundariesSSCU-3_0_0\/USA\/ADM1\/geoBoundariesSSCU-3_0_0-USA-ADM1.geojson", "imagePreview": "https:\/\/geoboundaries.org\/data\/geoBoundariesSSCU-3_0_0\/USA\/ADM1\/geoBoundariesPreviewSSCU-3_0_0-USA-ADM1.png" } ]