Unified Outage Schema

The unified outage schema represents a "golden record" created by correlating and merging outage data from multiple sources.

UnifiedOutage

interface UnifiedOutage {
  id: string;                          // Unique identifier

  // Temporal
  startedAt: string | null;            // When the outage started (ISO 8601)
  estimatedRestoration: string | null; // Estimated restoration time (ISO 8601)
  restoredAt: string | null;           // When power was restored (ISO 8601)

  // Geographic
  latitude: number | null;             // Latitude of outage centroid
  longitude: number | null;            // Longitude of outage centroid
  countyFips: string | null;           // 5-digit FIPS code for county
  stateFips: string | null;            // 2-digit FIPS code for state
  county: string | null;               // County name
  state: string | null;                // 2-letter state abbreviation

  // Utility
  utilityId: string | null;            // Utility identifier
  utilityName: string;                 // Utility display name

  // Impact
  customersAffected: number | null;    // Number of affected customers

  // Classification
  cause: OutageCause | null;           // Normalized cause category
  status: OutageStatus;                // Current status

  // Correlation metadata
  sourceCount: number;                 // Number of sources reporting this outage
  confidenceScore: number;             // Overall confidence score (0-1)
  primarySource: SourceName;           // Source with highest confidence
  sourceIds: string[];                 // IDs from each contributing source

  // Timestamps
  createdAt: string;                   // When the record was created (ISO 8601)
  updatedAt: string;                   // When the record was last updated (ISO 8601)
}

NormalizedOutage

Individual outage records from each source before correlation.

interface NormalizedOutage {
  id: string;                          // Unique identifier
  sourceId: string;                    // Original ID from the source
  sourceName: SourceName;              // Which source this came from

  // Temporal
  reportedAt: string;                  // When we received this data
  startedAt: string | null;            // When the outage started
  estimatedRestoration: string | null; // ETR from the source
  restoredAt: string | null;           // When restored
  lastUpdated: string;                 // Last update from source

  // Geographic
  latitude: number | null;
  longitude: number | null;
  countyFips: string | null;
  stateFips: string | null;
  county: string | null;
  state: string | null;
  city: string | null;
  zipCode: string | null;

  // Utility
  utilityId: string | null;
  utilityName: string;
  utilityNameRaw: string;              // Original utility name from source

  // Impact
  customersAffected: number | null;
  customersServed: number | null;      // Total customers served by utility

  // Classification
  cause: OutageCause | null;           // Normalized cause
  causeRaw: string | null;             // Original cause string
  status: OutageStatus;

  // Metadata
  rawData: Record<string, unknown>;    // Original source data
  ingestedAt: string;                  // When we ingested this record
  confidence: number;                  // Source-specific confidence (0-1)
}

Type Definitions

SourceName

type SourceName =
  | 'odin'           // Oak Ridge National Laboratory
  | 'poweroutage_us' // PowerOutage.us aggregator
  | 'caloes'         // California Office of Emergency Services
  | 'pge'            // Pacific Gas & Electric
  | 'duke'           // Duke Energy
  | 'sce'            // Southern California Edison
  | 'coned'          // Consolidated Edison (NYC)
  | 'fpl'            // Florida Power & Light
  | 'entergy'        // Entergy
  | 'dominion'       // Dominion Energy
  | 'doe417'         // DOE Form 417
  | 'eia';           // Energy Information Administration

OutageCause

type OutageCause =
  | 'weather'            // Storm, wind, lightning, ice, snow, flood
  | 'equipment_failure'  // Transformer, cable, line, pole failure
  | 'vegetation'         // Tree or vegetation contact
  | 'vehicle_accident'   // Vehicle collision
  | 'animal'             // Animal contact
  | 'planned_maintenance'// Scheduled work
  | 'fire'               // Fire or wildfire
  | 'earthquake'         // Seismic event
  | 'overload'           // Demand exceeded capacity
  | 'vandalism'          // Theft or intentional damage
  | 'unknown';           // Unknown or undetermined

OutageStatus

type OutageStatus =
  | 'active'         // Outage is ongoing
  | 'restored'       // Power restored
  | 'scheduled'      // Planned maintenance
  | 'investigating'; // Assessing situation

Confidence Scoring

Each unified outage has a confidence score (0-1) calculated from:

1. Base confidence: Average of source confidences
2. Multi-source bonus: +0.05 per additional source (max +0.15)
3. Data completeness bonus: Based on available fields

Source Confidence Levels

Source	Base Confidence
Direct utility APIs (PG&E, Duke, etc.)	0.85
Cal OES	0.75
ODIN	0.70

Field Completeness Bonuses

Field	Bonus
Latitude/Longitude	+0.15
Customers Affected	+0.10
Started At	+0.10
Utility ID	+0.10
Cause	+0.05

Example

{
  "id": "unified-pge-SF-2024122810-1703779200000",
  "startedAt": "2024-12-28T10:30:00.000Z",
  "estimatedRestoration": "2024-12-28T14:00:00.000Z",
  "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-SF-2024122810",
    "odin-PGE-06075-1703779200000"
  ],
  "createdAt": "2024-12-28T10:35:00.000Z",
  "updatedAt": "2024-12-28T11:00:00.000Z"
}