Outages API¶

The Outages API provides access to unified power outage data aggregated from multiple utility and government sources. The aggregator correlates and deduplicates outages from different sources to provide a single, high-confidence view of power outages across the US.

Base URL¶

https://ods-api.m-8b1.workers.dev

Endpoints¶

Get Unified Outages¶

Retrieve unified power outages with optional filtering.

GET /outages

Query Parameters¶

Parameter	Type	Description
`state`	string	Filter by US state abbreviation (e.g., "CA", "TX")
`county`	string	Filter by county name
`status`	string	Filter by status: `active`, `restored`, `scheduled`, `investigating`
`utility`	string	Filter by utility ID
`minConfidence`	number	Minimum confidence score (0-1)
`since`	string	Only return outages updated since this ISO timestamp
`limit`	number	Maximum results (default: 100, max: 1000)
`offset`	number	Pagination offset

Response¶

{
  "outages": [
    {
      "id": "unified-pge-12345-1703779200000",
      "startedAt": "2024-12-28T10:30:00Z",
      "estimatedRestoration": "2024-12-28T14:00:00Z",
      "restoredAt": null,
      "latitude": 37.7749,
      "longitude": -122.4194,
      "countyFips": "06075",
      "stateFips": "06",
      "county": "San Francisco",
      "state": "CA",
      "utilityId": "PGE",
      "utilityName": "Pacific Gas and Electric Co.",
      "customersAffected": 2500,
      "cause": "weather",
      "status": "active",
      "sourceCount": 2,
      "confidenceScore": 0.92,
      "primarySource": "pge",
      "sourceIds": ["pge-12345", "odin-67890"],
      "createdAt": "2024-12-28T10:35:00Z",
      "updatedAt": "2024-12-28T11:00:00Z"
    }
  ],
  "total": 150,
  "limit": 100,
  "offset": 0,
  "source": "database"
}

Get Live Outages¶

Force a fresh aggregation from all data sources.

GET /outages/live

Response¶

{
  "outages": [...],
  "normalized": 350,
  "stats": {
    "fetchDuration": 2500,
    "normalizeDuration": 150,
    "correlationDuration": 200,
    "totalDuration": 2850,
    "bySource": {
      "odin": { "raw": 100, "normalized": 98, "errors": 2 },
      "pge": { "raw": 50, "normalized": 48, "errors": 2 },
      "duke": { "raw": 75, "normalized": 75, "errors": 0 }
    }
  }
}

Get Outage Detail¶

Get detailed information about a specific unified outage, including all source data.

GET /outages/{outageId}

Response¶

{
  "outage": {
    "id": "unified-pge-12345-1703779200000",
    "utilityName": "Pacific Gas and Electric Co.",
    ...
  },
  "sources": [
    {
      "id": "pge-12345",
      "sourceName": "pge",
      "sourceId": "12345",
      "latitude": 37.7749,
      "longitude": -122.4194,
      "customersAffected": 2500,
      "confidence": 0.85,
      ...
    },
    {
      "id": "odin-67890",
      "sourceName": "odin",
      "sourceId": "67890",
      "customersAffected": 2450,
      "confidence": 0.70,
      ...
    }
  ]
}

Get Outage Statistics¶

Get aggregated statistics about stored outages.

GET /outages/stats

Response¶

{
  "totalUnified": 1250,
  "totalNormalized": 3500,
  "bySource": {
    "odin": 1500,
    "pge": 500,
    "duke": 450,
    "sce": 300,
    "coned": 200,
    "fpl": 550
  },
  "byState": {
    "CA": 450,
    "TX": 200,
    "FL": 300,
    "NY": 150
  },
  "byStatus": {
    "active": 150,
    "restored": 1000,
    "scheduled": 50,
    "investigating": 50
  }
}

Get Data Sources¶

List all available data sources and their health status.

GET /outages/sources

Response¶

{
  "sources": [
    {
      "sourceName": "odin",
      "refreshInterval": 300,
      "enabled": true,
      "healthy": true
    },
    {
      "sourceName": "pge",
      "refreshInterval": 600,
      "enabled": true,
      "healthy": true
    },
    {
      "sourceName": "duke",
      "refreshInterval": 600,
      "enabled": true,
      "healthy": false
    }
  ]
}

Trigger Aggregation¶

Manually trigger a data aggregation cycle.

POST /outages/aggregate

Response¶

{
  "success": true,
  "unified": 125,
  "normalized": 350,
  "stats": {
    "fetchDuration": 2500,
    "normalizeDuration": 150,
    "correlationDuration": 200,
    "totalDuration": 2850,
    "bySource": {...}
  }
}

Initialize Database¶

Initialize the D1 database schema for storing outages.

POST /outages/initialize

Response¶

{
  "success": true,
  "message": "Database schema initialized"
}

Data Sources¶

The aggregator collects data from multiple sources:

Source	Coverage	Refresh Rate
ODIN (ORNL)	National	5 minutes
PG&E	California	10 minutes
Duke Energy	NC, SC, FL, IN, OH, KY	10 minutes
SCE	Southern California	10 minutes
Con Edison	NYC, Westchester	10 minutes
FPL	Florida	10 minutes

Correlation¶

Outages from different sources are correlated based on:

Spatial overlap (35%): Geographic proximity using haversine distance
Temporal overlap (25%): Time window overlap
Utility match (25%): Fuzzy matching on utility names
Customer count similarity (10%): How close are the reported customer counts
Cause match (5%): If causes align

Outages scoring above 0.7 are merged into a single unified record.

Status Values¶

Status	Description
`active`	Outage is currently ongoing
`investigating`	Utility is assessing the situation
`scheduled`	Planned maintenance outage
`restored`	Power has been restored

Cause Values¶

Cause	Description
`weather`	Storm, wind, lightning, ice, snow, flood, hurricane, tornado
`equipment_failure`	Transformer, cable, line, pole, or hardware failure
`vegetation`	Tree or vegetation contact
`vehicle_accident`	Vehicle collision with infrastructure
`animal`	Animal contact (birds, squirrels, etc.)
`planned_maintenance`	Scheduled maintenance work
`fire`	Wildfire or fire-related
`earthquake`	Seismic event
`overload`	Demand exceeding capacity
`vandalism`	Theft or intentional damage
`unknown`	Cause not determined