Administrative units: geography#

Administrative units are the geographic regions by which property data is organized.

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

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

Administrative hierarchies of any depth are supported.

Default spine#

openplaces ships with a default “spine”: a canonical set of identifiers for the world:

src/openplaces/recipes/_all/admin/spine/2026

It is resolved for the first three administrative levels (countries > states > counties) and for part of the fourth (towns).

Identifiers come mostly from the Global Administrative Database (GADM). A few are already updated with official country datasets from published recipes (src/openplaces/recipes).

Administrative identifiers are a hybrid of prior systems (ISO, HASC) and codes created by openplaces derived from names.

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)

Disclaimer

The data mostly reflects the structure of GADM and is used for convenience, not political stance. The identifiers themselves need work to become more intuitive and reflective of global opinion and are therefore subject to change.

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()
Administrative units

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