geoBoundaries API

Free open administrative boundary API with no key: national, state and district boundaries for every country as downloadable GeoJSON, with licence and source metadata. Tested example included.

No API key requiredCORS enabledHTTPSFree tier

Endpoint tested and returned HTTP 200 on 2026-08-21

What is the geoBoundaries API?

geoBoundaries is a free, key-free API serving open administrative boundary polygons for every country in the world, from national outlines down to district level. Each response carries download links for the geometry plus the source, licence and vintage of the data.

Boundary data is normally either expensive or legally awkward, because national mapping agencies license it in incompatible ways. geoBoundaries, run out of William & Mary, solves that by only including openly licensed sources and recording the provenance of every layer — so the API response tells you which agency produced the polygons, under what licence, and when they were last revised.

The API is metadata first. A call for Italy at ADM1 returns not the polygons but a description of them: five units, an ISTAT source, a CC BY 3.0 licence, mean vertex counts and, crucially, `staticDownloadLink` and `gjDownloadURL` pointing at the actual GeoJSON. That indirection is deliberate — the geometry files run to megabytes, and you want them cached on your side rather than fetched per request. The `gbOpen` release used here is the fully open one; `gbHumanitarian` and `gbAuthoritative` exist alongside it with different sourcing rules.

Quick facts

Base URL: https://www.geoboundaries.org/api/current
Authentication: No key or account. Data is openly licensed by construction; individual layers carry their own licence, reported in the response.
Rate limit: No published quota for metadata calls. Geometry downloads are large, so fetch and cache them rather than requesting per user.
Pricing: Free. Licences vary by layer and are stated in `boundaryLicense`.
CORS: Enabled — callable directly from browser JavaScript
Official docs: Read the docs

How to use the geoBoundaries API

Every request below was executed against the live API on 2026-08-21, and the response shown is the real body it returned — not an illustration.

1. Get boundary metadata for a country's first administrative level

GET https://www.geoboundaries.org/api/current/gbOpen/ITA/ADM1/

curl

curl 'https://www.geoboundaries.org/api/current/gbOpen/ITA/ADM1/'

JavaScript (fetch)

const res = await fetch("https://www.geoboundaries.org/api/current/gbOpen/ITA/ADM1/");
if (!res.ok) throw new Error(`Request failed: ${res.status}`);
const data = await res.json();
console.log(data);

Python (requests)

import requests

res = requests.get("https://www.geoboundaries.org/api/current/gbOpen/ITA/ADM1/", timeout=20)
res.raise_for_status()
print(res.json())

Response — HTTP 200 (truncated)

{
  "boundaryID": "ITA-ADM1-72843720",
  "boundaryName": "Italy",
  "boundaryISO": "ITA",
  "boundaryYearRepresented": "2023",
  "boundaryType": "ADM1",
  "boundaryCanonical": "Unknown",
  "boundarySource": "ISTAT, National Institute of Statistics",
  "boundaryLicense": "Creative Commons Attribution 3.0 License",
  "licenseDetail": "nan",
  "licenseSource": "www.istat.it/it/note-legali",
  "boundarySourceURL": "www.istat.it/it/archivio/222527",
  "sourceDataUpdateDate": "Wed Aug 16 14:38:11 2023",
  "buildDate": "Dec 12, 2023",
  "Continent": "Europe",
  "UNSDG-region": "Europe and Northern America",
  "UNSDG-subregion": "Southern Europe",
  "worldBankIncomeGroup": "High-income Countries",
  "admUnitCount": "5",
  "meanVertices": "89847.0",
  "minVertices": "52782",
  "maxVertices": "160438",
  "meanPerimeterLengthKM": "3464.4468955457733",
  "minPerimeterLengthKM": "2862.0716459213654",
  "maxPerimeterLengthKM": "4439.01386743901",
  "meanAreaSqKM": "60279.964134362745",
  "minAreaSqKM": "49836.98871271305",
  "maxAreaSqKM": "73266.553411257",
  "staticDownloadLink": "https://github.com/wmgeolab/geoBoundaries/raw/9469f09/releaseData/gbOpen/ITA/ADM1/geoBoundaries-ITA-ADM1-all.zip",
  "gjDownloadURL": "https://github.com/wmgeolab/geoBoundaries/raw/9469f09/releaseData/gbOpen/ITA/ADM1/geoBoundaries-ITA-ADM1.geojson",
  "tjDownloadURL": "https://github.com/wmgeolab/geoBoundaries/raw/9469f09/releaseData/gbOpen/ITA/ADM1/geoBoundaries-ITA-ADM1.topojson",
  "imagePreview": "https://github.com/wmgeolab/geoBoundaries/raw/9469f09/releaseData/gbOpen/ITA/ADM1/geoBoundaries-ITA-ADM1-PREV

Parameters

Parameter	Type	Required	Description
`release`	path	Required	`gbOpen` for the fully open release, or `gbHumanitarian` / `gbAuthoritative`. `gbOpen`
`ISO`	path	Required	Three-letter ISO 3166-1 alpha-3 country code, or `ALL` for every country. `ITA`
`ADM`	path	Required	Administrative level: `ADM0` national, `ADM1` first subdivision, down to `ADM4`. `ALL` returns every available level. `ADM1`

Response fields

boundaryIDstring: Stable identifier for this specific boundary set and vintage.
boundaryName / boundaryISOstring: Country name and ISO alpha-3 code.
boundaryTypestring: The administrative level described, `ADM0` through `ADM4`.
boundarySource / boundarySourceURLstring: Which agency produced the polygons and where they came from — the provenance that makes the licence meaningful.
boundaryLicense / licenseSourcestring: Licence covering this layer. It varies by country, so check it rather than assuming.
boundaryYearRepresentedstring: The year the boundaries depict, which is not the same as the build date.
admUnitCountstring: How many units exist at this level — five regions for Italy at ADM1 would be wrong, so it is a quick sanity check on which release you got.
meanVertices / meanAreaSqKM / meanPerimeterLengthKMstring: Complexity and size statistics, useful for estimating download size and deciding whether to simplify.
staticDownloadLink / gjDownloadURLstring: URLs for the actual geometry. The API returns metadata; the polygons live at these links.

What you can build with the geoBoundaries API

Add country, state or district boundaries to a map without licensing negotiations
Check the licence and source of a boundary layer before shipping it
Aggregate statistics to consistent administrative units across countries
Estimate download size and vertex counts before pulling geometry
Compare boundary vintages when historical consistency matters

Common errors and how to fix them

The response has no geometry

By design — the API returns metadata about a boundary set.

Fix: Follow `gjDownloadURL` or `staticDownloadLink` for the GeoJSON itself, and cache it locally rather than fetching it per request.

404 for a country and level

That country does not publish an openly licensed layer at that level.

Fix: Query with `ADM=ALL` to see which levels exist for the country before requesting a specific one.

Numeric-looking fields are strings

`admUnitCount`, `meanVertices` and the area statistics are all returned as text.

Fix: Cast them explicitly. Some also carry the literal value "nan" where a statistic could not be computed.

Geometry is too heavy for a browser map

National polygons can exceed 100,000 vertices, as `meanVertices` warns.

Fix: Simplify the geometry before serving it to a client, or use vector tiles. Read `meanVertices` first to know what you are about to download.

geoBoundaries API — frequently asked questions

Is geoBoundaries free?

Yes, free with no key or account. Every included layer is openly licensed, and the specific licence for each is reported in the `boundaryLicense` field of the response.

Why does the API not return the polygons directly?

Because they are large — often several megabytes per country. The API returns metadata plus download URLs, which lets you check the licence, vintage and complexity before committing to the download.

What is the difference between gbOpen, gbHumanitarian and gbAuthoritative?

They are three releases with different sourcing rules. `gbOpen` includes only openly licensed data and is the safest default; `gbHumanitarian` follows UN OCHA sources; `gbAuthoritative` prefers the official national source even where licensing is more restrictive.

How current are the boundaries?

It varies by country, which is why every response carries `boundaryYearRepresented` alongside the build date. Check that field before comparing two countries in the same analysis.

Tools that pair with this API

GeoJSON Validator

Validate GeoJSON against RFC 7946 and get the exact JSON path of every problem: unclosed rings, swapped coordinates, missing properties and more.

GeoJSON Simplifier

Shrink GeoJSON with the Ramer-Douglas-Peucker algorithm at a tolerance in metres, and see the before-and-after outline and the file size saving.

GeoJSON to CSV Converter

Flatten a GeoJSON FeatureCollection into a CSV table with one row per feature, a centroid for lines and polygons, and every property as a column.

geoBoundaries is an independent third-party service and is not affiliated with ByteTools or ByteVancer. Details on this page were verified on 2026-08-21; always check the official documentation before relying on this API in production, as terms and limits can change.