USGS

Overview

The USGS Earthquake Hazards Program provides real-time earthquake data from a global network of seismometers. It is the most authoritative source for earthquake-specific measurements including precise magnitude, depth, Modified Mercalli Intensity (MMI), and community-reported "Did You Feel It?" data.

TerraGuard polls the USGS API every 2 minutes -- the most frequent polling interval of any data source, reflecting the time-critical nature of earthquake response.

What USGS Provides

USGS focuses exclusively on seismic events but provides significantly more detail than GDACS for earthquakes:

Data Format

USGS provides GeoJSON feeds at various time intervals:

TerraGuard uses the past hour feed by default to minimize response latency.

{
  "type": "FeatureCollection",
  "metadata": {
    "generated": 1711627200000,
    "url": "https://earthquake.usgs.gov/...",
    "title": "USGS All Earthquakes, Past Hour",
    "count": 12
  },
  "features": [
    {
      "id": "us7000n1ab",
      "type": "Feature",
      "geometry": {
        "type": "Point",
        "coordinates": [29.0875, 37.7749, 10.5]
      },
      "properties": {
        "mag": 6.5,
        "place": "15 km SSW of Denizli, Turkey",
        "time": 1711627180000,
        "updated": 1711627500000,
        "url": "https://earthquake.usgs.gov/earthquakes/eventpage/us7000n1ab",
        "title": "M 6.5 - 15 km SSW of Denizli, Turkey",
        "status": "automatic",
        "alert": "orange",
        "tsunami": 0,
        "mmi": 7.2,
        "felt": 1542,
        "cdi": 6.8,
        "sig": 650,
        "ids": ",us7000n1ab,nn00942857,ci40621784,"
      }
    }
  ]
}

Key Properties

The ID Aliasing Problem

The most significant technical challenge with USGS data is ID aliasing. When an earthquake occurs, multiple seismic networks detect it independently and assign their own IDs. Over time, these detections are merged into a single authoritative event, but the "winner" ID can change.

Example

An earthquake is detected by three networks:

Network:  US National       Nevada       Southern California
ID:       us7000n1ab        nn00942857   ci40621784

The USGS ids field contains all aliases: ",us7000n1ab,nn00942857,ci40621784," (note the leading and trailing commas -- this is part of the USGS format).

Initially, the primary feature ID might be nn00942857 (the first network to detect it). Hours later, after review, the primary ID changes to us7000n1ab. Without alias tracking, TerraGuard would treat this as two different earthquakes.

How the Adapter Handles It

The USGS adapter's ResolveIDs() method parses the ids field to extract all aliases:

func (a *USGSAdapter) ResolveIDs(raw model.RawEvent) []string {
    seen := make(map[string]struct{})
    var ids []string

    // Always include the primary feature ID.
    if raw.ID != "" {
        seen[raw.ID] = struct{}{}
        ids = append(ids, raw.ID)
    }

    // Parse the "ids" property field.
    idsStr := SafeString(raw.Properties, "ids", "")
    if idsStr != "" {
        parts := strings.Split(idsStr, ",")
        for _, part := range parts {
            id := strings.TrimSpace(part)
            if id == "" {
                continue
            }
            if _, exists := seen[id]; exists {
                continue
            }
            seen[id] = struct{}{}
            ids = append(ids, id)
        }
    }

    return ids
}

The pipeline then stores all aliases in the event_id_aliases table. When a future ingestion arrives with any of these IDs, the alias lookup finds the existing DisasterEvent and updates it rather than creating a duplicate.

Status Field

USGS events go through a review lifecycle:

The adapter explicitly filters out events with status: "deleted" during the polling phase.

Alert Level Mapping

USGS uses the PAGER (Prompt Assessment of Global Earthquakes for Response) system:

Note that USGS yellow is mapped to TerraGuard's ORANGE because the PAGER yellow level ("some damage possible") aligns more closely with the ORANGE tier than GREEN in humanitarian response contexts.

Measurements Extracted

The adapter extracts up to 6 measurements from each earthquake:

Additional data stored in AdditionalData:

• tsunami (boolean) -- Whether a tsunami warning was issued
• status -- Current review status
• type -- Event type (usually "earthquake")

Polling Configuration