Web-based Archival Access

File access has been standardized on the github platform. To download a file from the current release, you can navigate to our commits page, and choose the date (and commit) you are interested in retrieving files from. For convenience and research replication purposes, we further provide yearly releases of geoBoundaries. Archives for each of those releases can be found in the below table. Archived data prior to 1.3.4 is largely unstructured, but is available on request.

Release Date Single-country CGAZ
geoBoundaries 5.0.0 December 19, 2022 b7dd6a5 Download
geoBoundaries 4.0.0 August 31, 2021 299e006 Download
geoBoundaries 3.0.0 June 5, 2020 7c8dbc5 Download
geoBoundaries 2.0.0 December 7, 2019 375ea48 N/A
geoBoundaries 1.3.3 August 30, 2018 d3f7490 N/A


API Access to geoBoundaries

Information on every geoBoundary, including paths for geoJSONs, shapefiles, years of validity and more, can be retrieved through any http-compliant query; a JSON object is returned. We provide one endpoint for users: 
https://www.geoboundaries.org/api/current/[RELEASE-TYPE]/[3-LETTER-ISO-CODE]/[BOUNDARY-TYPE]/
  • [RELEASE-TYPE]
    This is one of gbOpen, gbHumanitarian, or gbAuthoritative. For most users, we suggest using gbOpen, as it is CC-BY 4.0 compliant, and can be used for most purposes so long as attribution is provided. gbHumanitarian files are mirrored from UN OCHA, but may have less open licensure. gbAuthoritative files are mirrored from UN SALB, and cannot be used for commerical purposes, but are verified through in-country processes. 
  • [3-LETTER-ISO-CODE]
    This is a ISO-3166-1 (Alpha 3) code for the country of interest. For example, "USA" for the United States, "GBR" for the United Kingdom, "CHN" for China, etc. The special code "ALL" is also accepted. 
  • [ADM-LEVEL]
    This is the type of boundary that you are interested in. Right now, we accept one of five different types: ADM0, ADM1, ADM2, ADM3, ADM4 and ADM5. ADM0 is the country boundary, ADM1 is the first level of subnational boundaries, ADM2 is the second level of subnational boundaries, and so on. For example, the United States has ADM0 (the country border), ADM1 (States), ADM2 (county) boundaries. The special code "ALL" is also accepted.
Once a request is made, a JSON is returned which contains the following fields (all returned objects are represented as strings; if a columnn is not guaranteed, it may return an empty string):
Element Guaranteed Definition Example
boundaryID Yes The ID for this layer, which is a combination of the ISO code, the boundary type, and a unique identifier for the boundary generated based on the input metadata and geometry. This only changes if the underlying data changes "ALB-ADM0-26141361"
boundaryName Yes The name of the country the layer represents "Albania"
boundaryISO Yes ISO-3166-1 (Alpha 3) code for the country "ALB"
boundaryYearRepresented Yes The year, or range of years in "[START] to [END]" format, which the boundary layers represent "2021" or "1995 to 2021"
boundaryType Yes The type of boundary "ADM1"
boundaryCanonical No The canonical name of a given boundary "Qarqet"
boundarySource Yes A comma-seperated list of the primary sources for the boundary "OCHA ROSEA, South African Municipal Demarcation Board"
boundarySource Yes A comma-seperated list of the primary sources for the boundary "OCHA ROSEA, South African Municipal Demarcation Board"
boundaryLicense Yes The original license that the dataset was released under by the primary source "Creative Commons Attribution 3.0 Intergovernmental Organisations (CC BY 3.0 IGO)"
licenseDetail No Any notes regarding the license. "License was confirmed by two parties and the official website provided in the metadata."
licenseSource Yes The URL of the primary source. "data.humdata.org/dataset/south-africa-admin-level-1-boundaries"
sourceDataUpdateDate Yes The date the source information was integrated into the geoBoundaries repository. "Wed Jun 9 14:10:43 2021"
buildDate Yes The date the source data was most recently standardized and built into a geoBoundaries release. "Jan 05, 2023"
Continent Yes The continent the country is associated with. "Africa"
UNSDG-region Yes The United Nations Sustainable Development Goals (SDG) region the country is associated with. "Sub-Saharan Africa"
UNSDG-subregion Yes The United Nations Sustainable Development Goals (SDG) subregion the country is associated with. "Southern Africa"
worldBankIncomeGroup Yes The World Bank income group the country is associated with. "Upper-middle-income Countries"
admUnitCount Yes Count of administrative units in the file. "1"
meanVertices Yes Mean number of vertices defining the boundaries of each administrative unit in the layer. "282824.0"
minVertices Yes Minimum number of vertices defining a boundary. "18365"
maxVertices Yes Maximum number of vertices defining a boundary. "38176456"
minPerimeterLengthKM Yes The minimum perimeter length of an administrative unit in the layer, measured in kilometers (based on a World Equidistant Cylindrical projection). "180.5741729203648"
meanPerimeterLengthKM Yes The mean perimeter length of all administrative units in the layer, measured in kilometers (based on a World Equidistant Cylindrical projection). "540.32156874946843"
maxPerimeterLengthKM Yes The maximum perimeter length of an administrative unit in the layer, measured in kilometers (based on a World Equidistant Cylindrical projection). "1584.804735999137"
meanAreaSqKM Yes The mean area of all administrative units in the layer, measured in square kilometers (based on a EASE-GRID 2 projection). "5731.517972980774"
minAreaSqKM Yes The minimum area of an administrative unit in the layer, measured in square kilometers (based on a EASE-GRID 2 projection). "545.4813798711891"
maxAreaSqKM Yes The maximum area of an administrative unit in the layer, measured in square kilometers (based on a EASE-GRID 2 projection). "44231.22640471353"
staticDownloadLink Yes The static download link for the aggregate zip file containing all boundary information.
gjDownloadURL Yes The static download link for the geoJSON.
tjDownloadURL Yes The static download link for the topoJSON.
imagePreview Yes The static download link for the automatically rendered PNG of the layer.
simplifiedGeometryGeoJSON Yes The static download link for the simplified geoJSON.