GDACS Tropical Cyclones

This module provides an interface to the GDACS (Global Disaster Alert and Coordination System) tropical cyclone API. It exposes event and episode metadata, per-advisory storm timelines, country- and admin-level population exposure, and a function to match a GDACS event to an NHC atcf_id. No authentication is required.

GDACS aggregates tropical cyclone advisories from multiple forecasting agencies (NOAA/NHC, JTWC). For storms forecast by the NHC, the GDACS forecast cone is the same underlying forecast as the NHC data, which is what makes matching a GDACS event to an NHC atcf_id possible (see Matching to NHC).

Quick Start

Finding events

import ocha_lens as lens

# Active and recent TC events (all alert levels)
gdf_events = lens.gdacs.get_events()

# Filter by date range and source
gdf_events = lens.gdacs.get_events(
    from_date="2024-09-01",
    to_date="2024-10-01",
    source="NOAA",
)

Storm timeline

# Per-advisory snapshots: position, wind speed, and population exposure
df_timeline = lens.gdacs.get_timeline(eventid=1000123)

Each row is one advisory. The actual flag distinguishes observed positions ("True") from forecast-cone positions ("False"). pop39/pop74 are instantaneous population snapshots within the 39 kt / 74 kt wind bands — not cumulative.

Population exposure

# Cumulative population exposure per wind buffer (~2022 onward)
adm0 = lens.gdacs.get_exposure_adm0(eventid=1000123)  # {"buffer39": df, "buffer74": df}
adm1 = lens.gdacs.get_exposure_adm1(eventid=1000123)  # sub-national grain

Each call returns a dict keyed by wind buffer ("buffer39", "buffer74"). The iso3 column carries GDACS’ native GMI_CNTRY code — apply lens.gdacs.to_iso3() to standardize the handful of X-prefixed territory codes to ISO 3166-1 alpha-3.

Matching to NHC

# Match a GDACS timeline to an NHC atcf_id
atcf_id = lens.gdacs.match_to_atcf(df_timeline, nhc_tracks)

match_to_atcf votes the GDACS forecast-cone points onto NHC atcf_ids by exact valid_time (the shared forecast cone agrees to ~0°), with a single-point genesis match as a fallback for completed storms. It returns None for non-NHC (JTWC/RSMC) storms. The caller must pass NHC tracks de-duplicated to one row per (atcf_id, valid_time) at the freshest issuance — see the function’s API reference for the exact contract.

Notes

• Coverage: timelines are available for events from 2015 onward; per-buffer population exposure is available for events from roughly 2022 onward.

• Errors: the module raises explicit exceptions (NoEpisodesError, NoTimelineError, EpisodeUrlFormatError) rather than silently returning empty data, so API-contract changes surface loudly.

See the API reference for full function signatures.