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.

Loading with Python
Visualizing with Python
Generic Example

	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"])

Returns the geometric shape(s) representing one of the administrative boundaries:

{'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")

Creates this figure (named example.png):

All requests to our API will return either an error (i.e., no file exists for the parameters passed to us) or a valid JSON object. A valid call and example are included here.
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"
    }
]