Admin-boundary data (GADM)¶
Climate-Lama uses GADM v4.1 as its authoritative source of administrative boundaries (admin-0 / 1 / 2). Boundaries back the zoom-aware aggregation surface — a damage or exposure value is attached to a country, region, or district polygon so the UI can summarise results at whatever zoom level the viewport is showing.
Why GADM¶
- Global, single consistent schema. One file covers every country with the
same attribute layout (
GID_0,NAME_1,GID_1, …). Stitching per-country sources would add continuous maintenance cost and create seams at borders. - Hierarchy is explicit. Each admin-N row carries
GID_{N-1}, so the parent-child relationship is a direct join — no geometric "which polygon contains this one" disambiguation needed at ingest time. - Permissive enough for our use. Research and non-commercial redistribution are allowed with attribution. Commercial redistribution requires written permission; the managed-hosting deployment must obtain it before shipping.
What we load¶
The load script pulls the GADM v4.1 global levels
archive and writes one row per polygon into admin_boundaries
(migration 0031).
| Level | Meaning | Default? | Opt-in flag |
|---|---|---|---|
| 0 | Country | yes | — |
| 1 | First-level sub | yes | — |
| 2 | Second-level sub | no | LOAD_ADMIN_2=true |
Admin-2 is gated because the dump is large (≈300k rows, several hundred MB). Most Phase-4 deployments only need admin-0/1; tenants rendering zoom-3 tiles can flip the flag and re-run the loader.
Attribution¶
Every row is stamped with source="GADM", version="4.1", plus license,
citation, and source_url mirroring the open-data attribution contract on
other catalog entities (see [issue
204](https://github.com/CortoMaltese3/climate-lama/issues/204)). The shared¶
attribution_dict helper in api/attribution.py serialises the
block unchanged, so any future admin-boundary endpoint surfaces attribution
identically to hazards, exposures, and impact functions.
The bundled license string includes the GADM non-commercial clause verbatim
so downstream UI "About this data" dialogs render the full terms without a
follow-up DB migration.
Disputed borders¶
GADM renders contested territories from a single editorial position that does not match every member state's claims. The highest-visibility cases as of v4.1 are:
- Crimea. Included under Ukraine (
UKR) as a first-level subdivision (Republic of Crimea,GID_1 = "UKR.5_1"). - Kashmir. The India–Pakistan–China region is split along the de-facto
Line of Control. GADM places Jammu & Kashmir and Ladakh under India (
IND) and Azad Kashmir / Gilgit-Baltistan under Pakistan (PAK); Aksai Chin is assigned to China (CHN). - Western Sahara. GADM ships it as a separate admin-0 entity (
ESH) rather than under Morocco.
These choices are not endorsements — they are the editorial state of a third-party dataset we consume. Climate-Lama does not amend GADM's geometries or ISO codes; any downstream product that needs an alternative rendering must post-process the rows in its own view or layer.
For readers who need a UI-level disclosure, surface the attribution block
verbatim next to any map that renders boundaries — source_url points at
gadm.org/data.html, which is the authoritative place to read GADM's own
position on disputed territories.
Re-running the loader¶
The loader upserts on (source, version, iso3, admin_level, name, parent_id).
Running it twice on the same GADM version is a no-op — the ON CONFLICT
clause refreshes geometries and attribution columns but creates no duplicates.
To move to a new GADM version, bump GADM_VERSION in the script and re-run;
old rows remain (query by version to pin a tenant to an older release while
the new load is validated).