Administrative units: geography#

Administrative units are the geographic regions at which property data is organized. They mostly refer to countries and in-country subdivisions.

openplaces uses a globally resolvable, hierarchical (multi-level) set of identifiers for administrative units.

Levels#

Four levels of administrative units are currently supported:

	Description	In code	Examples of identifiers
0	Earth		`None`
1	Countries & territories	`admin1`	`US` United States `CO` Colombia
2	States, departments, etc.	`admin2`	`US-MA` state of Massachusetts `CO-AN` department of Antioquia
3	Counties, municipalities, etc.	`admin3`	`US-MA-MI` Middlesex county, Massachusetts, U.S. `CO-AN-ME` municipality of Medellín, Colombia
4	Cities, towns, subdivisions, etc.	`admin4`	`US-MA-MI-SO` city of Somerville Not all countries have level-4 IDs in the default recipe

Identifiers#

openplaces comes with default tables of global identifiers for administrative units to simplify data exchange between users (admin-openplaces-2026, see recipe on Github).

The identifiers are derived in large part from the Global Administrative Database (GADM) and supplemented with in-country updates from official country datasets.

Administrative identifiers are a hybrid of existing codes and codes generated by openplaces. These choices reflect pragmatic reasons (available data), not political opinions, and will likely change as data and choices improve.

Example breakdown: US-MA-MI-SO (city of Somerville in the state of Massachusetts, U.S.)

US and MA: from the International Organization for Standardization (ISO)
MI (Middlesex county): based on HASC codes obtained from GADM.
SO (Somerville): generated internally (no prior standard)

Spatial boundaries#

If you want to make maps of administrative boundaries or use them for geoprocessing (e.g., identifying all building footprints within a county), you need to import the boundaries from their original source.

Official boundaries#

To import official in-country geometries (e.g., as a reference for your geoprocessing), run this notebook with a country recipe:

notebooks/02_ingest/admin/ingest_admin.ipynb

Global boundaries#

To import global geometries (GADM, >2 GB), run this notebook:

notebooks/01_setup/03_ingest_global_administrative_units.ipynb

After that, you can make precise global maps.

from openplaces.api import get_admin

get_admin(geom=True).plot()

Note that these are large geometry files and will take a while to render (~10 seconds).