API & Archival Access

Web-based Archival Access

All versions of geoBoundaries can be accessed using a simple online file browser located at https://www.geoboundaries.org/data/. Further, since 2.0 all versions can also be accessed through our API, as detailed below. Versions prior to 2.0 are made available through the online file browser only; these files are not standardized to the same standard of our contemporary releases.

Archival data for any boundary can also be accessed by adjusting any single boundaries URL. For example, if you are looking at the files for Norway in version 2.0.0 of geoBoundaries, the URL you would use is https://www.geoboundaries.org/data/geoBoundaries-2_0_0/NOR/. To see version 2.0.1, you can simply adjust the URL to https://www.geoboundaries.org/data/geoBoundaries-2_0_1/NOR/.

API Access to geoBoundaries

Information on every geoBoundary - current and past - can be retrieved through a simple query; a JSON object is returned:

https://www.geoboundaries.org/gbRequest.html?ISO=[3-LETTER-ISO-CODE]&ADM=[ADM-LEVEL]

Users can also enter special phrases "ALL" for either "ADM" or "ISO" to get a multi-boundary return (within the element 'geoBoundaries'). A full list of parameters users can include are:

ISO - Optional; defaults to 'ALL'. The three-letter ISO code representing the country of interest. The special phrase 'ALL' can be entered to return all ISO codes in the database.
ADM - Optional; defaults to 'ALL'. One of ADM0, ADM1, ADM2, ADM3, ADM4 or ADM5, representing each level of administrative hierarchy. The special phrase 'ALL' can be entered to return all levels available.
VER - Optional; defaults to the most recent version of geoBoundaries available. The geoboundaries version requested, with underscores. For example, 3_0_0 would return data from version 3.0.0 of geoBoundaries.
TYP - Optional; defaults to HPSCU. One of HPSCU, HPSCGS, SSCGS, or SSCU. Determines the type of boundary link you receive.

HPSCU - High Precision Single Country Unstadardized. The premier geoBoundaries release, representing the highest precision files available for every country in the world. No standardization is performed on these files, so (for example) two countries may overlap in the case of contested boundaries.
HPSCGS - High Precision Single Country Globally Standardized. A version of geoBoundaries high percision data that has been clipped to the U.S. Department of State boundary file, ensuring no contested boundaries or overlap in the dataset. This globally standardized product may have gaps between countries. If you need a product with no gaps, we recommend our simplified global product.
SSCU - Simplified Single Country Unstandardized. A simplified version of every file available for every country in the world. No standardization is performed on these files, so (for example) two countries may overlap in the case of contested boundaries.
SSCGS - Simplified Single Country Globally Standardized. A version of geoBoundaries simplified data that has been clipped to the U.S. Department of State boundary file, ensuring no contested boundaries or overlap in the dataset. This globally standardized product may have gaps between countries.

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