massoutage

MassOutage API

A free, open-CORS JSON API for US power outages: live county status, municipalities, incidents and threshold alerts, plus a decade of history.

v1 is additive-only, so nothing here removes or renames a field. Breaking changes would be announced here at least 90 days ahead and ship under a new version.

  1. Severity by share of customers out

    • addedband and magnitude on every county and state in GET /api/v1/live/map: [customers_out, pct_out, level, band, magnitude]. band is the 0-5 share ramp (1/3/10/25/50% of customers out) the map now colours by, or -1 where no denominator can be trusted; magnitude is a 0-5 headcount ramp.
    • changedlevel is superseded by band. Its formula is unchanged, so existing consumers keep the same semantics: a blend of magnitude, percent and neighbour concentration in which raw headcount alone could reach the top of the scale: 20,000 out in a 3.4-million-customer county scored the same as a county with 60% out. Note that level does move for counties whose percentage was previously clamped, because that input is now correct.
    • fixedA county denominator smaller than the outage is no longer clamped to 100%. pct_out is null instead, wherever it appears: the live map, county rollups and the threshold API. Some modelled county customer counts are implausibly small, and clamping made exactly those counties read as fully out.
    • changedCounty percentages now prefer the denominator the feeds themselves publish over the modelled county customer count, taking the larger of the two.

  2. Annual report data tables

    • addedGET /api/v1/reports/data?table=national|states: year-over-year national totals with EAGLE-I coverage and every state-year with prior-year change. Years not loaded yet are returned with loaded: false and null values.
    • addedGET /api/v1/reports/{year}/data?table=counties|events|states|months|causes|disturbances and GET /api/v1/reports/{year}/{state}/data?table=counties|events|months|causes, with ?format=csv.
    • addedGET /api/v1/reports/{year}/{state}/{county}/data?table=summary|years|months|events|causes|utilities: the county annual report, including outage episodes by size, longest episode, state and national comparisons and EIA-861 SAIDI/SAIFI of serving utilities.

  3. Per-source polling cadence

    • addedtier, interval_min and next_due_at on every source in GET /api/v1/live/sources.
    • changedLive sources now poll on their own cadence rather than one shared interval, and a source is polled harder while the utility it covers has 1% or more of its customers out or its counties are being watched.
    • changedA source counts as stale once its last successful fetch is older than twice its interval plus 5 minutes (minimum 20), and updated_at is now when that source was last fetched.

  4. Outage event stream, feeds and webhooks

    • addedGET /api/v1/events: outage_began, outage_grew, etr_changed, outage_improving, outage_restored, major_event, feed_stale and feed_recovered for counties, municipalities and utilities, with ?after cursor paging and ?fips, ?state, ?utility, ?kind, ?min_customers, ?since and ?limit filters. No account needed.
    • addedFeeds with the same filters: /feeds/events.rss, /feeds/events.atom and /feeds/events.json (JSON Feed 1.1).
    • addedSigned webhooks (MassOutage-Signature: t=…,v1=HMAC-SHA256) plus Slack, Teams, Discord and email delivery for account alert rules, and scheduled data sync pushes of county snapshot, areas, incidents, alert status and state summary. Documented in the OpenAPI webhooks section.
    • changedOutages close only after two polls below half the opening threshold, and never while the feed covering them is stale.
    • changedPOST /api/v1/alerts/subscribe now returns 410 Gone: email alerts moved to account alert rules.

  5. County operations endpoints, request tracing and developer docs

    • addedEvery v1 response now carries X-Request-Id, X-API-Version: 1 and X-Data-Notice headers, and v1 routes answer CORS preflight (OPTIONS) requests.
    • addedGET /api/v1/live/counties/{fips}/areas: municipalities and townships as each utility reports them, including masked ("<N") outages, with ?format=csv and ?format=geojson.
    • addedGET /api/v1/live/counties/{fips}/incidents: individual outages with ETR, crew status and cause, with ?format=csv and ?format=geojson.
    • addedGET /api/v1/live/counties/{fips}/alerts: ?min_customers and ?min_pct thresholds evaluated for the county, each utility (with the 10% major-event line) and each municipality.
    • addedFilters: ?utility, ?active=true and ?min_customers on areas; ?utility and ?min_customers on incidents; ?utility on alerts. These endpoints' JSON also returns meta.notice and meta.filters.
    • addedconnector_coverage in GET /api/v1/live/sources: US customers split by how each utility is seen live (county, utility total, outage-only, no feed).
    • addedOpenAPI 3.1 document at GET /api/v1/openapi.json.
    • dataemPOWER (HHS) electricity-dependent Medicare beneficiary counts on county pages.
    • dataNew Jersey PSE&G and JCP&L now report exact county and town customer counts.

  6. CSV export

    • added?format=csv on county, county history, causes, county live and trend data endpoints.

  7. v1 launch

    • addedFree, open-CORS JSON API: live summary, map, top, timeline, sources and county live status; county profile, history and causes; OE-417 disturbances; trend data; branded chart PNGs.