The shared geography key
across every pack.

Using loc_id in queries

loc_id is the shared machine-facing geography key across the pack layer. Pass it in filters.region_ids to scope a query to one or more locations. Keep it in returned rows — it is the stable join handle when you want to combine results across packs or calls.

Most first queries only need a few obvious ISO3 country codes: JPN, CHL, IDN, USA. Those are enough to make any of the seven packs work on the first call.

Hierarchical matching

Event sources store geography at varying levels of specificity. A broad region filter such as JPN still matches event records nested under more specific sub-regions, because the runtime treats location as a tree rather than a flat lookup. You do not need to know the exact nested id to get results — start broad and narrow down.

Pack-specific region ids

Not every pack uses only ISO3 country codes. Two current cases to know:

• Tsunamis — supports both country codes (JPN) and ocean-region ids (XOO). Ocean ids are real source buckets, not broken country codes.
• Hurricanes — uses basin codes: XNA (North Atlantic), XOP (Pacific), XIN (Indian Ocean). ISO3 country codes also work for landfalling storm queries.

Check the pack detail for the region id shapes a specific pack supports.

In client code

Store loc_id in your result rows even when the UI shows a friendlier label. Render a display name next to it if needed, but keep the id as the stable key. Do not assume every pack uses plain ISO3 as its deepest location unit.

Organizing your own data with loc_ids

If you are packaging a dataset for use with the runtime, your data needs to use loc_id values that align with the geometry layer. This is what makes cross-pack joins and map rendering work.

The id pattern

loc_id follows a hierarchical structure:

{ISO3}[-{admin1}[-{admin2}[-{admin3}...]]]

Country codes are ISO 3166-1 alpha-3, uppercase. Sub-national levels extend the id with a hyphen-separated suffix.

Geometry compatibility rule

A loc_id is only useful if it matches the geometry files the runtime uses for map rendering and spatial joins. If your data uses a custom admin code or FIPS-style id, you need a crosswalk that maps it to the canonical loc_id before the data enters the pack layer. The runtime supports documented crosswalk bridges — it does not auto-normalize arbitrary id formats.

Data schema basics

Two schema shapes use loc_id as the primary geography key:

• Aggregate data — one row per (loc_id, year). Used for indicators, demographics, economic metrics. Do not add redundant name columns if loc_id already identifies the place.
• Event data — one row per event, with loc_id as the geography field. Events also carry event_id, timestamp, latitude, and longitude.

Conversion pattern

Normalize geography into loc_id early in your converter — before any other transformations. A dataset that cannot cleanly produce valid loc_id values is not ready for the pack layer.

import pandas as pd

df = pd.read_csv("raw_data.csv")
df = df.rename(columns={"region_code": "loc_id", "data_year": "year"})
df["year"] = pd.to_numeric(df["year"], errors="coerce")
df["value"] = pd.to_numeric(df["value"], errors="coerce")
df = df[["loc_id", "year", "value"]]
df.to_parquet("output.parquet", index=False)

What to avoid

• Storing names instead of stable ids — names change, ids do not.
• Mixing multiple geography systems in one file without a crosswalk.
• Using raw FIPS codes or GEOID values if they are not the canonical loc_id format.
• Duplicating geometry metadata (name, admin level, parent) in every data row — that belongs in the geometry layer.