GDACS

Overview

GDACS (Global Disaster Alert and Coordination System) is the primary data source for TerraGuard. It is a cooperation framework between the United Nations, the European Commission, and disaster management organizations worldwide. GDACS provides near-real-time alerts about natural disasters and tools to facilitate response coordination.

TerraGuard polls the GDACS API every 5 minutes to ingest events across all disaster types.

What GDACS Provides

GDACS covers the broadest range of disaster types of any TerraGuard data source:

Data Format

GDACS returns events as a GeoJSON FeatureCollection. Each feature represents a single event or episode:

{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "geometry": {
        "type": "Point",
        "coordinates": [29.0875, 37.7749]
      },
      "properties": {
        "eventid": 1234567,
        "episodeid": 1,
        "eventtype": "EQ",
        "name": "Earthquake in Turkey",
        "alertlevel": "Red",
        "alertscore": 3.5,
        "country": "Turkey",
        "description": "M 6.5 earthquake...",
        "fromdate": "2026-03-28T10:15:00Z",
        "todate": "2026-03-28T10:15:00Z",
        "datemodified": "2026-03-28T10:30:00Z",
        "severitydata": {
          "severity": 6.5,
          "severityunit": "M"
        },
        "htmldescription": "https://www.gdacs.org/report.aspx?eventid=1234567"
      }
    }
  ]
}

Key Properties

Alert Level System

GDACS uses a three-tier alert level system based on the predicted humanitarian impact:

TerraGuard maps these directly to its own alert level enum:

How the Adapter Works

The GDACS adapter in the Event Processor (internal/adapter/gdacs.go) handles the full ingestion flow:

1. Polling

The adapter fetches the GDACS events API:

GET https://www.gdacs.org/gdacsapi/api/events/geteventlist/EVENTS4APP
Accept: application/json

2. Event ID Construction

GDACS events are identified by a composite key of eventid and episodeid. The adapter constructs a canonical source event ID:

gdacs:{eventid}:{episodeid}

For example, event 1234567, episode 1 becomes gdacs:1234567:1.

3. Normalization

The adapter maps GDACS fields to the NormalizedEvent format:

4. Measurement Extraction

Measurements are extracted based on event type from the severitydata object:

The alertscore is always recorded as a secondary measurement.

GDACS Unique Characteristics

Event vs. Episode

GDACS distinguishes between events and episodes. An earthquake is a single event, but a tropical cyclone may have multiple episodes (advisories) as it develops. The Event Processor handles this through its correlation pipeline -- multiple episodes with the same eventid are correlated to the same DisasterEvent in the database.

Impact Geometry

For some event types (particularly tropical cyclones and floods), GDACS provides polygon geometries representing the estimated impact area. The adapter passes this through as ImpactGeometry in the normalized event, which is stored alongside the point location.

Severity Data

The severitydata object contains the primary measurement in source-specific units. The adapter normalizes the unit string based on the event type, ensuring consistent measurement types across the platform.

Polling Configuration