API documentation
Metadata and download URLs over HTTP. No API key required.
Build an API request
The API returns a JSON object for a single boundary, or a list for
queries using ALL. The response includes source
information, the year represented, and links to boundary files.
Open a download URL to retrieve the geometry.
Python example
import requests
url = "https://geoboundaries-dev.org/api/nightly/gbOpen/USA/ADM1/"
response = requests.get(url, timeout=30)
response.raise_for_status()
boundary = response.json()
print(boundary["gjDownloadURL"])This example requests one boundary. When using ALL, iterate over the returned list. The nightly endpoint changes as data is updated; use a fixed release for reproducible analysis.
Release types
| Release | Source & use |
|---|---|
gbOpen |
Recommended for most projects. Open data under CC BY 4.0; attribution required. |
Endpoint format
https://geoboundaries-dev.org/api/[VERSION]/gbOpen/[ISO-3]/[ADM-LEVEL]/
Levels run from ADM0 (country boundaries) to
ADM5 (more local subdivisions). Coverage varies by
country. Use ALL in place of the ISO code or level to
list available boundaries.
Response fields
Metadata values are generally returned as strings. Optional fields may be empty. Download fields provide links to files; the API response itself contains metadata.
| 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-separated 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. |
Archived releases
Available versions come from the live release catalog. Formal releases are fixed; nightly follows the latest successful publication. Download URLs returned by the API name the resolved snapshot.
Loading published versions…
| Release | Date | Single-country | CGAZ |
|---|
Older, unstructured archives are available on request.