Event Processor API Reference

API reference for the TerraGuard event processor, including health, adapter, metrics, polling, and test endpoints for replaying disaster events.

Overview

The event processor is a Go service responsible for polling external disaster data sources, normalizing events, and writing them to PostgreSQL. It exposes operational endpoints for monitoring and test endpoints for development.

Base URL: http://localhost:5606 (local development)

Authentication: None required for local development. In production, the service is not publicly exposed.

Operational Endpoints

Health Check

GET /health

Returns the service health status and uptime.

{
  "status": "healthy",
  "uptime": "2h34m12s",
  "adapters": {
    "gdacs": "enabled",
    "usgs": "enabled",
    "nhc": "disabled"
  }
}

List Adapters

GET /adapters

Returns all registered data source adapters with their status, poll interval, and event counts.

{
  "adapters": [
    {
      "name": "gdacs",
      "enabled": true,
      "poll_interval": "5m",
      "last_poll": "2025-03-28T08:15:00Z",
      "last_status": "success",
      "events_processed": 47
    }
  ]
}

Metrics

GET /metrics

Returns processing metrics for monitoring.

{
  "total_events_processed": 171,
  "total_events_created": 85,
  "total_events_updated": 62,
  "total_events_skipped": 24,
  "total_poll_cycles": 340,
  "total_poll_errors": 2,
  "uptime_seconds": 9252
}

Trigger Poll

POST /poll/{adapter}

Manually triggers a poll cycle for the specified adapter.

Parameter	Type	Description
`adapter`	string	Adapter name: `gdacs`, `usgs`, or `nhc`

curl -X POST http://localhost:5606/poll/gdacs

{
  "adapter": "gdacs",
  "events_found": 12,
  "events_created": 3,
  "events_updated": 5,
  "events_skipped": 4,
  "duration_ms": 1847
}

Test Endpoints

These endpoints are available only in development mode and allow replaying sample disaster events without connecting to live data sources.

List Test Files

GET /test/files

Returns available test fixture files.

[
  "myanmar-earthquake.json",
  "turkey-flood.json",
  "japan-tsunami.json",
  "atlantic-hurricane.json"
]

Preview Events in File

GET /test/files/{name}/events

Returns parsed events from a test file without processing them.

Parameter	Type	Description
`name`	string	Test file name (e.g., `myanmar-earthquake.json`)

curl http://localhost:5606/test/files/myanmar-earthquake.json/events

{
  "file": "myanmar-earthquake.json",
  "adapter": "gdacs",
  "event_count": 3,
  "events": [
    {
      "index": 0,
      "source_id": "EQ-2025-001",
      "title": "M7.7 Earthquake - Myanmar",
      "event_type": "earthquake",
      "severity": "red",
      "latitude": 20.88,
      "longitude": 95.95
    }
  ]
}

Ingest Single Test Event

POST /test/files/{name}/events/{index}

Processes a single event from a test file through the full ingestion pipeline.

Parameter	Type	Description
`name`	string	Test file name
`index`	integer	Event index within the file (0-based)

curl -X POST http://localhost:5606/test/files/myanmar-earthquake.json/events/0

{
  "action": "created",
  "event_id": "evt_abc123",
  "source_id": "EQ-2025-001",
  "webhook_sent": true
}

Additional Test Ingest Endpoints

Endpoint	Description
`POST /test/ingest`	Ingest a single custom event by providing the full event payload as JSON
`POST /test/ingest/batch`	Ingest multiple events in a single request via an `events` array
`POST /test/ingest/file`	Process all events from a named test file through the pipeline
`POST /test/ingest/raw`	Ingest raw source data (XML/JSON) for testing adapter parsing

Save Poll Response

POST /test/save-poll/{adapter}

Polls the live data source and saves the raw response as a test fixture file for future replay.

Parameter	Type	Description
`adapter`	string	Adapter name: `gdacs`, `usgs`, or `nhc`

curl -X POST http://localhost:5606/test/save-poll/gdacs

{
  "adapter": "gdacs",
  "file_saved": "gdacs-2025-03-28T08-15-00.json",
  "events_in_response": 15
}

This is useful for capturing real data source responses to use as test fixtures later.

Event Processor API Reference

On this page