Concepts

Urban Data Center organizes data around the Urban Agglomeration: a contiguous urban region represented by a single boundary and stable identifier. The UA is the primary dimension. Boundaries, administrative splits, pollution measures, population histories, and future datasets all attach to that dimension at a declared grain.

Urban Agglomerations

An Urban Agglomeration is the unit used to describe a city-scale built-up region. It is not a municipality, district, metro authority, or a direct copy of an administrative boundary. Administrative systems vary significantly across countries; the UA provides researchers with a globally consistent city object for cross-national comparison.

Each UA boundary is a single polygon representing a contiguous built-up extent. Associated metadata includes name, population estimate, country code, and area. All other datasets use the same UA identifiers so measures can be joined to city objects without rebuilding the city definition.

Identifiers

Each UA has a ua_id that is derived from the H3 grid used in the boundary-generation workflow. Identifiers are intended to be stable across releases: when a dataset is updated, downstream joins continue to work against the same city object.

Names are descriptive labels — useful for display, but not reliable as keys across data sources. Always join on ua_id.

Administrative splits

ADM1 and ADM2 splits subdivide a UA into its constituent administrative units. They are partitions of the parent boundary, not an independent GADM table joined by spatial overlap.

Administrative boundaries come from GADM. Each split polygon is the intersection of the parent UA boundary with the relevant GADM feature. Every split belongs to exactly one parent UA.

ADM1 splits are identified by (ua_id, adm1_split_id) — the parent agglomeration plus the split’s own identifier within that parent.

ADM2 splits are identified by (ua_id, adm2_split_id) — the same pattern at the finer administrative level.

Inclusion criteria

ADM splits are only produced when there is a meaningful partition to expose. A UA that falls entirely within a single ADM1 boundary has no ADM1 split product — the split would be identical to the parent boundary. The same logic applies at ADM2: if all ADM2 units within the UA belong to the same higher-level unit, no ADM2 split is generated.

In practice this means:

  • Small or geographically compact cities may have a UA boundary but no ADM1 or ADM2 split dataset entries.
  • Larger agglomerations that span multiple provinces or districts will have both ADM1 and ADM2 split products.

Dataset grains

Datasets publish at one of three grains:

  • ua_id — one row per Urban Agglomeration.
  • (ua_id, adm1_split_id) — one row per UA-scoped ADM1 split.
  • (ua_id, adm2_split_id) — one row per UA-scoped ADM2 split.

Choose the coarsest grain that matches the research question. Use UA-level data for cross-city comparisons and city-wide aggregates. Use ADM1 or ADM2 splits when the within-city distribution matters and the measure is meaningful at that finer level.