Administrative boundaries — quickstart (geoBoundaries)¶
The earthlens.admin backend fetches administrative-boundary polygons from four
public sources and returns them as a pyramids FeatureCollection in EPSG:4326.
This quickstart pulls the first sub-national level (ADM1) for one country from
geoBoundaries and maps it.
By the end you will know how to: pick a dataset id, pass the selector it needs
(country=), call download(), and read the returned polygons. See the
admin reference for the full API.
Setup¶
earthlens exposes every backend through the unified EarthLens facade. The admin
backend needs no credentials — all four sources are public.
from earthlens import EarthLens
import matplotlib.pyplot as plt
Fetch ADM1 for one country¶
A request names a dataset id via variables= and the selector that dataset
needs. geoBoundaries is country-indexed, so it needs country= (an ISO-3166-1
alpha-3 code). Here we ask for Kenya's 47 counties (geoboundaries:adm1).
kenya_adm1 = EarthLens(
data_source='admin',
variables=['geoboundaries:adm1'],
country='KEN',
).download(progress_bar=False)
len(kenya_adm1)
2026-06-28 16:47:37 | INFO | pyramids.base.config | Logging is configured.
2026-06-28 16:47:38.400 | INFO | earthlens.earthlens:__init__:1012 - No `path` given; download() writes 'admin' output under earthlens-data\admin/ (load() uses a temp dir).
2026-06-28 16:47:38.881 | INFO | earthlens.admin.backend:_fetch:330 - Fetching geoboundaries:adm1 from geoboundaries (/vsicurl/https://github.com/wmgeolab/geoBoundaries/raw/9469f09/releaseData/gbOpen/KEN/ADM1/geoBoundaries-KEN-ADM1.geojson)
2026-06-28 16:47:38.882 | INFO | earthlens.admin.backend:_fetch:332 - geoboundaries license: geoBoundaries (gbOpen), CC-BY-4.0; cite Runfola, D. et al. (2020) geoBoundaries: A global database of political administrative boundaries.
2026-06-28 16:47:42.112 | INFO | earthlens.admin.backend:_fetch:335 - geoboundaries:adm1: read 47 feature(s)
2026-06-28 16:47:42 | INFO | pyogrio._io | Created 47 records
2026-06-28 16:47:42.208 | INFO | earthlens.admin.backend:download:412 - admin download summary: 47 feature(s) written to C:\gdrive\algorithms\remote-sensing\earthlens\.claude\worktrees\admin\docs\examples\admin\earthlens-data\admin\admin_geoboundaries_adm1.gpkg
47
geoBoundaries is a two-step source: the backend first calls the gbOpen API for
the (country, ADM level) pair, reads the GeoJSON download URL from the metadata,
then reads that file through pyramids. The result is already EPSG:4326.
print('CRS EPSG:', kenya_adm1.crs.to_epsg())
print('columns:', list(kenya_adm1.columns))
kenya_adm1[['shapeName', 'shapeISO', 'shapeType']].head()
CRS EPSG: 4326 columns: ['shapeName', 'shapeISO', 'shapeID', 'shapeGroup', 'shapeType', 'geometry']
| shapeName | shapeISO | shapeType | |
|---|---|---|---|
| 0 | Turkana | KE-43 | ADM1 |
| 1 | Marsabit | KE-25 | ADM1 |
| 2 | Mandera | KE-24 | ADM1 |
| 3 | Wajir | KE-46 | ADM1 |
| 4 | West Pokot | KE-47 | ADM1 |
Map the boundaries¶
Every admin result is a GeoDataFrame-like FeatureCollection, so it plots directly
with the geopandas/matplotlib stack. Each polygon is one county.
ax = kenya_adm1.plot(edgecolor='black', facecolor='#cfe8d4', figsize=(7, 7))
ax.set_title('Kenya ADM1 (geoBoundaries) — 47 counties')
ax.set_xlabel('Longitude')
ax.set_ylabel('Latitude')
plt.show()
Takeaway¶
variables=['geoboundaries:adm<N>']+country=<ISO3>returns that country's ADM-N boundaries as polygons in EPSG:4326.- geoBoundaries serves ADM0–ADM5; swap the id (
geoboundaries:adm2, …) for finer levels. - The other three sources (CGAZ, Natural Earth, TIGER) follow the same
download()shape — see the catalog-explorer and multi-source notebooks.