Incident Schema¶

The Incident type is the core data structure for all outage and incident data.

TypeScript Definition¶

interface Incident {
  // Required fields
  id: string;
  kind: "power" | "network";
  status: "ongoing" | "resolved";
  startedAt: string;  // ISO 8601 timestamp
  confidence: number; // 0.0 to 1.0
  summary: string;
  source: string;

  // Optional fields
  endedAt?: string | null;
  region?: string;
  asn?: string | null;
  customersAffectedEstimate?: number | null;
  incidentCause?: string | null;
  expectedResolutionTime?: string | null;
  lat?: number | null;
  lon?: number | null;
  severity?: "minor" | "moderate" | "major";
}

Field Descriptions¶

Required Fields¶

Field	Type	Description
`id`	string	Unique identifier, format: `{source}-{detail}-{index}`
`kind`	string	Incident type: `"power"` or `"network"`
`status`	string	Current state: `"ongoing"` or `"resolved"`
`startedAt`	string	ISO 8601 timestamp when incident began
`confidence`	number	Data reliability score from 0.0 to 1.0
`summary`	string	Human-readable description
`source`	string	Data source identifier

Optional Fields¶

Field	Type	Description
`endedAt`	string \| null	ISO 8601 timestamp when resolved
`region`	string	Geographic region (e.g., "Alameda, CA")
`asn`	string \| null	Autonomous System Number (e.g., "AS13335")
`customersAffectedEstimate`	number \| null	Estimated customer impact
`incidentCause`	string \| null	Cause category
`expectedResolutionTime`	string \| null	Estimated restoration time
`lat`	number \| null	Latitude for mapping
`lon`	number \| null	Longitude for mapping
`severity`	string	Impact level: `"minor"`, `"moderate"`, `"major"`

ID Format¶

Incident IDs follow a consistent format for traceability:

{source}-{identifier}-{index}

Examples: - odin-pge-12345-0 - ODIN incident from PG&E - radar-evt-789 - Cloudflare Radar event - caloes-54321 - Cal OES incident - bgp-US-AS12345-1705312800 - BGP event with timestamp

Cause Categories¶

Value	Description
`WEATHER`	Weather-related (storms, ice, wind)
`EQUIPMENT_FAILURE`	Infrastructure malfunction
`VEGETATION`	Tree/vegetation contact
`PLANNED_MAINTENANCE`	Scheduled work
`BGP_WITHDRAWAL`	BGP route withdrawal
`BGP_UPDATE`	Significant BGP change
`TRAFFIC_ANOMALY`	Unusual traffic patterns
`null`	Unknown or unspecified

Confidence Interpretation¶

Range	Level	Typical Sources
0.8 - 1.0	High	Radar, Kentik (curated data)
0.6 - 0.8	Medium	ODIN, Cal OES, NWS (official data)
0.4 - 0.6	Lower	BGP (raw feeds)

JSON Example¶

{
  "id": "odin-pge-12345-0",
  "kind": "power",
  "status": "ongoing",
  "startedAt": "2025-01-15T10:30:00Z",
  "endedAt": null,
  "confidence": 0.7,
  "summary": "Power outage in Alameda, CA (utility: PG&E)",
  "region": "Alameda, CA",
  "asn": null,
  "customersAffectedEstimate": 1500,
  "source": "odin",
  "incidentCause": "WEATHER",
  "expectedResolutionTime": "2025-01-15T14:00:00Z",
  "lat": 37.7652,
  "lon": -122.2416,
  "severity": "moderate"
}