API

Public, read-only, no key required

Free to use. These figures are collected from public outage data and arenot guaranteed to be accurate or complete; they are provided without warranty. If you use them, cite NS Utility Tracking (outagemap.hfxdeploy.com).

Authentication

Every endpoint is a plain GET. Nothing is written, and no key or header is required.

Rate Limit

A short burst is allowed, then requests refill at one every six seconds. Over the limit returns 429 with a JSON body. The limit applies to /api/… only, not to this page or the dashboard.

Format

Responses are { data, meta }. Timestamps are ISO 8601 in UTC; the dashboard displays Atlantic time, so the two differ by three or four hours.

Endpoints

GET/api/summary

Current system state: the newest published reading, totals since logging began, and the last collector run.

/api/summary

GET/api/outages

Individual outages, newest first.

status: active | restored (default: both)
hours: only outages first seen in the last N hours
limit: 1 to 1000, default 100
offset: for paging

/api/outages?status=active&limit=20

GET/api/events

The append-only update log: every change observed in the utility's feed.

type: opened, restored, etr_set, etr_changed, etr_cleared, etr_missed, customers_changed, cause_changed
hours: only events in the last N hours
limit: 1 to 1000, default 100
offset: for paging

/api/events?type=restored&limit=20

GET/api/areas

Service area readings. Without hours, the latest reading for each of the utility's areas; with hours, the full time series over that window.

hours: return the time series over the last N hours
limit: 1 to 1000, default 100 (series mode only)

/api/areas

GET/api/snapshots

System-wide totals, one row per generation the utility published.

hours: only generations in the last N hours
limit: 1 to 1000, default 100
offset: for paging

/api/snapshots?hours=24&limit=10

GET/api/causes

Outage types and how many of each have been logged.

/api/causes

GET/api/export

CSV rather than JSON, streamed. Datasets: outages, events, snapshots, areas, runs.

dataset: required, one of the five above
hours: limit to the last N hours
type: filter events by event type

/api/export?dataset=outages

Examples

# what is out right now
curl -s https://outagemap.hfxdeploy.com/api/summary

# the twenty most recent restorations
curl -s 'https://outagemap.hfxdeploy.com/api/events?type=restored&limit=20'

# the whole outage table as CSV
curl -O -J 'https://outagemap.hfxdeploy.com/api/export?dataset=outages'

Notes

Customer counts marked customers_masked: 1 are rounded up by the utility to protect the privacy of very small outages, so per-area figures can total more than the system-wide number.
An outage stays active until it has been absent from two consecutive publications, which avoids reporting a false restoration when it briefly drops out of the feed.
Nothing is ever deleted or aged out, so hours is the only thing narrowing a response besides limit.