DaedalMap
Docs / loc_id

The one field that makes
the data join cleanly.

loc_id is the shared location key across the DaedalMap runtime. If you understand how it works, most of the API becomes easier to reason about.

Default

Use loc_id for joins

When two results can be meaningfully joined by location, loc_id is the intended shared key.

Hierarchy

Prefixes matter

Many source families support hierarchical matching, which means a broader regional id can match nested local event ids underneath it.

Exception

Tsunamis mix styles

Tsunami queries are a little different because they can route through country names or ocean-region identifiers like XOO.

What loc_id is

loc_id is DaedalMap’s normalized location identifier. It is the field the runtime prefers to use in responses because it is stable across packs and more explicit than display names alone.

Why it matters

If you query disasters in one call and population or indicator data in another, the cleanest join path is usually location plus time. On the location side, loc_id is the intended shared handle.

How hierarchical matching works

Some event sources store specific event-level or nested geographic ids under a broader parent region. In those cases, passing a broader region such as an ISO3 country code can still match the nested records because the runtime treats the source as a hierarchical location tree rather than a flat lookup table.

Simple mental model

Think of loc_id as the canonical geographic key in the runtime, and think of pack-specific display names as friendly labels layered on top. If you need a join key, prefer loc_id. If you need human-readable output, render both.

Tsunami region routing is a little different

The tsunami source supports both hierarchical-style ids and a country-name lookup mode. That is why a request may use country-oriented ids like JPN or ocean-region ids like XOO. For tsunami queries, those ocean-region ids are not mistakes; they represent real water-region buckets in the source contract.

Practical advice

If you are building a first integration, keep the query narrow and inspect the returned loc_id values before trying to build larger joins or mixed-source workflows.

What to document in client code

Treat loc_id as a machine-facing identifier, not a UI label. Keep it in your stored results, show a friendlier label next to it, and do not assume every pack uses plain ISO3 country codes as the deepest location unit.