COD-ABs: the common map of a humanitarian response

• Admin boundaries form a common operational picture of humanitarian activities, sourced from national authorities if possible
• P-codes: a stable code for every unit, down to the lowest level available
• Maintained by OCHA for the countries where it operates

COD-AB stands for Common Operational Dataset for Administrative Boundaries. In a crisis, everyone responding needs to agree on where the provinces and districts are and what they’re called. The COD-AB is that shared reference, endorsed in-country and published openly. In Cameroon, each P-code extends its parent’s: Yoko is CMR.002.004.005, inside Mbam-et-Kim (CMR.002.004), inside Centre (CMR.002).

OCHA maintains COD-ABs for 114 of 248 countries and territories, including every country with an active humanitarian response plan this year.

Tabular data on HDX joins on COD-ABs

These are the kinds of tabular data on HDX, and they all locate their rows by admin unit through COD-AB P-codes. HAPI, the HDX Humanitarian API, standardizes indicators from many organizations into one schema. Nine of its thirteen indicators are reported by admin unit, and they line up only because they share COD-AB P-codes. It also showed that standardizing other people’s data after the fact doesn’t scale.

The Humanitarian Data Model replaces it, and its draft is being agreed across agencies. Most of HAPI’s data carries over into the model’s domains, and the model adds new ones. Every domain locates its data through the Location domain, which holds the admin boundaries.

Boundaries are how people get counted

People in need are counted by district, against a baseline population for that district, and that’s how aid gets targeted. Here it’s Afghanistan in 2025: 22.9 million people in need out of 46 million.

400 of the 401 districts in the needs data join to the COD-AB on their P-code. The one that doesn’t is Khulm, coded AF2110 in the needs data and AF2008 in the boundaries, so a plain join silently drops it.

Each agency keeps its own global boundaries

• OCHA, WFP, UNICEF, UNHCR and IOM each maintain one, and so do FAO, the World Bank and others, often for internal enterprise systems
• Their field presence is complementary: they overlap in some countries, and in others only one agency is there

Each dot is a country where OCHA has a country office, a regional office or a humanitarian advisory team. That’s where OCHA has people with local knowledge of the boundaries.

The other agencies each have their own map like this, and their own global boundary dataset built from it. Where they overlap, there are competing versions. Where they don’t, one agency may hold the only good data.

Even where the geography matches, the codes differ

The same city, with the same boundary, carries a different code in each source. So data gets re-coded every time it moves between agencies, and joins break when a code is mapped wrong.

A COD-AB gets built in round trips between field and HQ

• Field teams know the ground truth: which boundary is correct, how many divisions there are at each level, and what places are called
• HQ knows data quality: cleaning topology, keeping codes and versions consistent, and catching name encoding errors
• A question one side can’t answer goes to the other, and each trip adds friction

Country offices and national agencies know the ground, but the cleaning and coding happen centrally. A dataset needs both, so files go back and forth until it’s right.

UN80 brought the agencies to the same table

• UN80: reform across the UN system to bring efficiency, with one evidence base for humanitarian data
• Rome, June 2026: five UN humanitarian agencies agreed one P-code standard, one update process, and a global COD-AB by the end of 2026
• Then the broader humanitarian community from 2027

UN80 is the reform effort across the UN system. Its report commits to a Humanitarian Data Collaborative so that all actors can work from one evidence base.

For boundaries, that meant getting the five agencies in a room. Over three days in Rome, they agreed the P-code specification, the governance process for updates, and the roadmap. The rollout starts with OCHA’s own process, then the five agencies, then partners like FAO and the World Bank.

A standard only works if it’s easy to follow

• The tools were built alongside the standard and tested on real COD-ABs while it was still being agreed
• Field teams run the same checks as HQ, so problems are caught before data is sent, with fewer round trips
• Built for staff who don’t use code: everything also runs in a web browser

A standard written only as a document tends to get read once and followed loosely. When the rules are built into the tools people already use, following the standard is simply what the tools do, and the check tells you right away if something’s off.

The tools also use open, widely used formats and P-codes that follow UN Secretariat conventions, so nothing locks partners in.

Cleaning in six steps

1. 1SchemaMap source columns to codes and names
2. 2TopologyFind and fix gaps and overlaps
3. 3Edge matchingFit units to the reference outline
4. 4CodesCarry codes over from the last release
5. 5NamesFix encoding, spacing and duplicates
6. 6PackagingBuild polygons, points and lines

Every boundary update goes through the same six steps: map the source schema, clean the topology, match the edges to the international boundary, carry the codes over from the last release, clean the names, and package the result.

Each demo later in the talk is one of these steps.

Two tools, starting with the CLI

• The Python CLI came first, because it’s faster to iterate on and handles big data
• The web app was developed alongside it, porting the logic to WASM and building a UI on top

Each step is DuckDB spatial SQL, with GeoParquet between steps, so any intermediate result can be opened and checked. Because the logic lives in SQL, the same queries run in the browser.

Building the CLI: tools, then docs, then skills

• The CLI commands came first: institutional knowledge made deterministic
• Docs came next: goal-oriented Diátaxis how-to guides, one per step, chained from raw data to release
• Skills came last, so agents can follow the docs and run the CLI

The skills are optional. They open the CLI up to colleagues who are comfortable with data but aren’t software developers. OCHA’s Field Information Services team works this way in VS Code on Windows.

Validated on every COD-AB, then ported to the browser

• OCHA converted its COD-AB catalog to a Portolan catalog to test against, then ran every dataset from raw to cleaned
• The hard algorithmic work happens in Python, then ports to JS with the UI added on top, so both stay at feature parity
• Field teams get the same tools HQ uses, in a browser with nothing to install
• Files stay on the local machine, so nothing has to be uploaded over a slow connection

Some partners don’t have Python or an AI subscription, and some can’t install software at all. The browser app is a static site with no server, built with Astro, Svelte and MapLibre. Most of the work went into making the UI easy to use.

The demo uses Netherlands admin boundaries. Each of the next slides embeds one tool, live, with its demo file loaded.