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.

Generated from the OpenAPI 3.1.0 document (version 1.x) served at /api/v1/openapi.json. Import it into Postman, Insomnia or a code generator. All responses include X-Request-Id, X-API-Version and X-Data-Notice headers.

Counties

County profile, history and causes.

GET/api/v1/counties/{fips}

County profile: live snapshot + yearly history

County metadata, a live customers-out snapshot, yearly reliability history and serving utilities. `?format=csv` downloads the yearly series.

Parameter	In	Type	Description
fips*	path	string	5-digit county FIPS code (state + county), e.g. 34025 for Monmouth County, NJ.
format	query	json \| csv	Response format; csv returns the yearly series.

200: application/json, text/csv404: Unknown county.500: Unexpected server error. `request_id` matches the X-Request-Id header.

Response fields (33)

Field	Type	Description
data	object
data.fips	string	5-digit county FIPS.
data.name	string	County name.
data.state	string	State name.
data.state_abbr	string	USPS state abbreviation.
data.url	string	Canonical MassOutage county page.
data.live	object
data.live.customers_out	integer	Customers out right now.
data.live.incident_count	integer	Active incidents.
data.latest_year	object \| null	Most recent EAGLE-I year (latest year of any source when none); null without history.
data.latest_year.year	integer	Calendar year.
data.latest_year.source	string	Dataset slug (eaglei = DOE/ORNL EAGLE-I, odin = live).
data.latest_year.customer_minutes	number	Total customer-minutes of outage.
data.latest_year.peak_customers_out	integer	Peak simultaneous customers out.
data.latest_year.event_count	integer	Outage episodes.
data.latest_year.customers_tracked	integer \| null	Customers in the county (denominator).
data.latest_year.avg_minutes_per_customer	number \| null	SAIDI-like average minutes without power per customer.
data.yearly	array	Yearly reliability history.
data.yearly[].year	integer	Calendar year.
data.yearly[].source	string	Dataset slug (eaglei = DOE/ORNL EAGLE-I, odin = live).
data.yearly[].customer_minutes	number	Total customer-minutes of outage.
data.yearly[].peak_customers_out	integer	Peak simultaneous customers out.
data.yearly[].event_count	integer	Outage episodes.
data.yearly[].customers_tracked	integer \| null	Customers in the county (denominator).
data.yearly[].avg_minutes_per_customer	number \| null	SAIDI-like average minutes without power per customer.
data.utilities	array	Utilities serving the county.
data.utilities[].id	string	Utility key.
data.utilities[].name	string	Utility name.
meta	object	Dataset-level provenance. Omitted when there is nothing to report.
meta.sources	array	Datasets this response draws on, for citation.
meta.sources[].name	string	Upstream dataset name.
meta.sources[].url	string	Resolvable URL of the upstream dataset.
meta.last_modified	string \| null	When the underlying data last changed (live poll time on live endpoints).

Example response (illustrative values)

{
  "data": {
    "fips": "34025",
    "name": "Monmouth County",
    "state": "New Jersey",
    "state_abbr": "NJ",
    "url": "https://massoutage.com/new-jersey/monmouth-county",
    "live": {
      "customers_out": 1840,
      "incident_count": 27
    },
    "latest_year": {
      "year": 2025,
      "source": "eaglei",
      "customer_minutes": 10000000,
      "peak_customers_out": 40000,
      "event_count": 30,
      "customers_tracked": 350000,
      "avg_minutes_per_customer": 28.5
    },
    "yearly": [
      {
        "year": 2025,
        "source": "eaglei",
        "customer_minutes": 10000000,
        "peak_customers_out": 40000,
        "event_count": 30,
        "customers_tracked": 350000,
        "avg_minutes_per_customer": 28.5
      }
    ],
    "utilities": [
      {
        "id": "9726",
        "name": "Jersey Central Power & Lt Co"
      }
    ]
  },
  "meta": {
    "sources": [
      {
        "name": "ODIN (Outage Data Initiative Nationwide)",
        "url": "https://odin.ornl.gov/"
      }
    ],
    "last_modified": "2026-09-14T13:50:00.000Z"
  }
}

GET/api/v1/counties/{fips}/history

County monthly history and worst events

Monthly outage series, worst recorded episodes and yearly history. `?format=csv` downloads the monthly series.

Parameter	In	Type	Description
fips*	path	string	5-digit county FIPS code (state + county), e.g. 34025 for Monmouth County, NJ.
format	query	json \| csv	Response format; csv returns the monthly series.

200: application/json, text/csv404: Unknown county.500: Unexpected server error. `request_id` matches the X-Request-Id header.

Response fields (32)

Field	Type	Description
data	object
data.fips	string	County FIPS.
data.name	string	County name.
data.state	string	State name.
data.monthly	array
data.monthly[].year	integer	Year.
data.monthly[].month	integer	Month 1-12.
data.monthly[].source	string	Dataset slug.
data.monthly[].customer_minutes	number	Customer-minutes of outage.
data.monthly[].peak_customers_out	integer	Peak customers out.
data.monthly[].event_count	integer	Outage episodes.
data.monthly[].minutes_any_outage	number	Minutes with any customer out.
data.worst_events	array
data.worst_events[].started_at	string	Episode start.
data.worst_events[].ended_at	string	Episode end.
data.worst_events[].duration_min	number	Duration in minutes.
data.worst_events[].peak_customers_out	integer	Peak customers out.
data.worst_events[].customer_minutes	number	Customer-minutes.
data.worst_events[].source	string	Dataset slug.
data.yearly	array
data.yearly[].year	integer	Calendar year.
data.yearly[].source	string	Dataset slug (eaglei = DOE/ORNL EAGLE-I, odin = live).
data.yearly[].customer_minutes	number	Total customer-minutes of outage.
data.yearly[].peak_customers_out	integer	Peak simultaneous customers out.
data.yearly[].event_count	integer	Outage episodes.
data.yearly[].customers_tracked	integer \| null	Customers in the county (denominator).
data.yearly[].avg_minutes_per_customer	number \| null	SAIDI-like average minutes without power per customer.
meta	object	Dataset-level provenance. Omitted when there is nothing to report.
meta.sources	array	Datasets this response draws on, for citation.
meta.sources[].name	string	Upstream dataset name.
meta.sources[].url	string	Resolvable URL of the upstream dataset.
meta.last_modified	string \| null	When the underlying data last changed (live poll time on live endpoints).

GET/api/v1/counties/{fips}/causes

County outage-cause mix

Accumulated historical cause mix and the live cause mix. `?format=csv` downloads the historical mix (live mix when there is no history).

Parameter	In	Type	Description
fips*	path	string	5-digit county FIPS code (state + county), e.g. 34025 for Monmouth County, NJ.
format	query	json \| csv	Response format.

200: application/json, text/csv404: Unknown county.500: Unexpected server error. `request_id` matches the X-Request-Id header.

Response fields (29)

Field	Type	Description
data	object
data.county	object
data.county.fips	string	County FIPS.
data.county.name	string	County name.
data.county.state	string \| null	State abbreviation.
data.historical	object
data.historical.ranked	array	Classified categories, largest first.
data.historical.ranked[].category	string enum	Cause category. (weather, equipment, vegetation, wildlife, vehicle, planned, publicSafety, vandalism, unknown)
data.historical.ranked[].label	string	Display label.
data.historical.ranked[].hex	string	Chart color.
data.historical.ranked[].weight	number	customer_minutes (historical) or customers_out (live).
data.historical.ranked[].share_pct	number	Share of the classified total.
data.historical.attributedPct	number	Percent of the total with a reported cause.
data.historical.totalWeight	number	Classified + unknown weight.
data.historical.unknownWeight	number	Weight with no reported cause.
data.historical.monthsCovered	integer	Distinct months of history (0 for live).
data.historical.metric	string enum	Unit of weight. (customer_minutes, customers_out)
data.live	object
data.live.ranked	array	Classified categories, largest first.
data.live.ranked[].category	string enum	Cause category. (weather, equipment, vegetation, wildlife, vehicle, planned, publicSafety, vandalism, unknown)
data.live.ranked[].label	string	Display label.
data.live.ranked[].hex	string	Chart color.
data.live.ranked[].weight	number	customer_minutes (historical) or customers_out (live).
data.live.ranked[].share_pct	number	Share of the classified total.
data.live.attributedPct	number	Percent of the total with a reported cause.
data.live.totalWeight	number	Classified + unknown weight.
data.live.unknownWeight	number	Weight with no reported cause.
data.live.monthsCovered	integer	Distinct months of history (0 for live).
data.live.metric	string enum	Unit of weight. (customer_minutes, customers_out)

Live

Live outage status, refreshed about every 10 minutes.

GET/api/v1/live/summary

National and per-state live totals

National live totals, coverage split and states ranked by customers out. Suitable for polling every 5 minutes.

No parameters.

200: application/json500: Unexpected server error. `request_id` matches the X-Request-Id header.

Response fields (32)

Field	Type	Description
data	object
data.national	object
data.national.customers_out	integer	National customers out (county-level + not localized).
data.national.incident_count	integer	Active incidents.
data.national.county_count	integer	Counties with customers out.
data.national.state_count	integer	States with live data.
data.national.unmapped_out	integer	Customers out known only at utility/state level.
data.national.updated_at	string \| null	Time of the latest live poll.
data.national.as_of	string \| null	Oldest region's data time; older than updated_at means some region is carried forward.
data.national.stale	boolean	True when any region's data is being carried forward.
data.national.stale_out	integer	Customers out whose source is being carried forward (stale).
data.coverage	object
data.coverage.sources	integer	Configured live sources reporting this poll.
data.coverage.sources_ok	integer	Sources that fetched successfully this poll.
data.coverage.customers_out	integer	National total.
data.coverage.county_level_out	integer	Customers out localized to a county.
data.coverage.not_localized_out	integer	Customers out known only at utility/state level.
data.coverage.tracked_customers	integer	Measured floor of customers under live watch.
data.states	array	States ranked by customers out.
data.states[].state_fips	string	2-digit state FIPS.
data.states[].name	string	State name.
data.states[].abbr	string	USPS abbreviation.
data.states[].slug	string	URL slug.
data.states[].url	string	Relative MassOutage state page URL.
data.states[].customers_out	integer	Customers out in the state.
data.states[].county_count	integer	Counties with customers out.
data.states[].unmapped_out	integer	Customers out not placed on a county.
meta	object	Dataset-level provenance. Omitted when there is nothing to report.
meta.sources	array	Datasets this response draws on, for citation.
meta.sources[].name	string	Upstream dataset name.
meta.sources[].url	string	Resolvable URL of the upstream dataset.
meta.last_modified	string \| null	When the underlying data last changed (live poll time on live endpoints).

Example response (illustrative values)

{
  "data": {
    "national": {
      "customers_out": 184203,
      "incident_count": 9412,
      "county_count": 611,
      "state_count": 49,
      "unmapped_out": 12050,
      "updated_at": "2026-09-14T13:50:00.000Z",
      "as_of": "2026-09-14T13:50:00.000Z",
      "stale": false,
      "stale_out": 0
    },
    "coverage": {
      "sources": 64,
      "sources_ok": 62,
      "customers_out": 184203,
      "county_level_out": 172153,
      "not_localized_out": 12050,
      "tracked_customers": 98000000
    },
    "states": [
      {
        "state_fips": "34",
        "name": "New Jersey",
        "abbr": "NJ",
        "slug": "new-jersey",
        "customers_out": 5210,
        "county_count": 12,
        "unmapped_out": 0,
        "url": "/new-jersey"
      }
    ]
  },
  "meta": {
    "sources": [
      {
        "name": "ODIN (Outage Data Initiative Nationwide)",
        "url": "https://odin.ornl.gov/"
      }
    ],
    "last_modified": "2026-09-14T13:50:00.000Z"
  }
}

GET/api/v1/live/map

Compact severity map of every county and state out

Keyed arrays for choropleths: `[customers_out, pct_out, level, band, magnitude]`. `band` is the 0-5 share-of-customers ramp the map colours by (1/3/10/25/50%), or -1 where no denominator can be trusted; `magnitude` is a 0-5 headcount ramp. `level` is the pre-2026-09 blend, superseded by `band`; its formula is unchanged, though it moves where a clamped percentage was corrected.

No parameters.

200: application/json500: Unexpected server error. `request_id` matches the X-Request-Id header.

Response fields (4)

Field	Type	Description
data	object
data.generated_at	string	When this response was generated.
data.counties	object	County FIPS → `[customers_out, pct_out, level, band, magnitude]`. `band` is the 0-5 share-of-customers ramp the map colours by (1/3/10/25/50%), or -1 where no denominator can be trusted; `magnitude` is a 0-5 headcount ramp. `level` is the pre-2026-09 blend, superseded by `band`; its formula is unchanged, though it moves where a clamped percentage was corrected. Only counties with customers out appear.
data.states	object	State FIPS → `[customers_out, pct_out, level, band, magnitude]`. `band` is the 0-5 share-of-customers ramp the map colours by (1/3/10/25/50%), or -1 where no denominator can be trusted; `magnitude` is a 0-5 headcount ramp. `level` is the pre-2026-09 blend, superseded by `band`; its formula is unchanged, though it moves where a clamped percentage was corrected.

Example response (illustrative values)

{
  "data": {
    "generated_at": "2026-09-14T13:50:00.000Z",
    "counties": {
      "34025": [
        1840,
        0.53,
        2
      ]
    },
    "states": {
      "34": [
        5210,
        0.13,
        2
      ]
    }
  }
}

GET/api/v1/live/top

Ranked live leaders

Top 8 states (with top live cause), counties and providers by customers out.

No parameters.

200: application/json500: Unexpected server error. `request_id` matches the X-Request-Id header.

Response fields (21)

Field	Type	Description
data	object
data.states	array
data.states[].state_fips	string	State FIPS.
data.states[].name	string	Name.
data.states[].abbr	string	Abbreviation.
data.states[].slug	string	Slug.
data.states[].customers_out	integer	Customers out.
data.states[].county_count	integer	Counties out.
data.states[].top_cause	string \| null	Leading live cause label.
data.counties	array
data.counties[].fips	string	County FIPS.
data.counties[].name	string	Name.
data.counties[].slug	string	Slug.
data.counties[].state_slug	string	State slug.
data.counties[].state_abbr	string	State abbreviation.
data.counties[].customers_out	integer	Customers out.
data.providers	array
data.providers[].eia_id	string \| null	EIA utility id.
data.providers[].name	string	Name.
data.providers[].slug	string	Slug.
data.providers[].customers_out	integer	Customers out.

GET/api/v1/live/timeline

State severity timeline

State-level 0-5 severity resampled to 48 evenly spaced frames over the window.

Parameter	In	Type	Description
hours	query	number, default 24	Window length in hours (clamped 1-48).

200: application/json500: Unexpected server error. `request_id` matches the X-Request-Id header.

Response fields (5)

Field	Type	Description
data	object
data.hours	number	Applied window.
data.frames	array
data.frames[].t	string	Frame time.
data.frames[].states	object	State FIPS → level 0-5 (absent = 0).

GET/api/v1/live/sources

Feed health and coverage (status endpoint)

How the live feeds did on their last poll in aggregate, the county-level vs not-localized split, and connector coverage of US customers. Use it as the status endpoint: check `feeds.down` and `coverage.sources_ok` before trusting a number. Per-feed rows are not published; which utility we read at what resolution is not part of the contract.

No parameters.

200: application/json500: Unexpected server error. `request_id` matches the X-Request-Id header.

Response fields (27)

Field	Type	Description
data	object
data.coverage	object
data.coverage.sources	integer	Configured live sources reporting this poll.
data.coverage.sources_ok	integer	Sources that fetched successfully this poll.
data.coverage.customers_out	integer	National total.
data.coverage.county_level_out	integer	Customers out localized to a county.
data.coverage.not_localized_out	integer	Customers out known only at utility/state level.
data.coverage.tracked_customers	integer	Measured floor of customers under live watch.
data.feeds	object
data.feeds.total	integer	Live feeds configured.
data.feeds.live	integer	Feeds that answered on the last poll and are within their freshness window.
data.feeds.stale	integer	Feeds serving carried-forward last-good data.
data.feeds.down	integer	Feeds that failed with no recent data (their areas show a gap).
data.feeds.customers_out_before_dedupe	integer	Customers out summed across feeds, before overlapping feeds are merged. Higher than the national total.
data.feeds.oldest_last_ok_ts	string \| null	Oldest successful fetch across all feeds.
data.connector_coverage	object
data.connector_coverage.total_customers	integer	Customers on the wires of every utility with an EIA-861 service territory, counted once each (bundled + delivery). Retail-only suppliers are excluded; see Denominator.
data.connector_coverage.county_customers	integer	Customers of utilities reported by county every poll (0 out is a real all-clear).
data.connector_coverage.utility_customers	integer	Customers of utilities reported as a utility total every poll, not by county.
data.connector_coverage.outage_only_customers	integer	Customers of utilities that appear in feeds only while they have outages.
data.connector_coverage.blind_customers	integer	Customers of utilities with no live feed.
data.connector_coverage.eia_year	integer \| null	EIA-861 year of the customer counts.
data.denominator	object
data.denominator.wires_customers	integer	Customers on the wires of a utility with an EIA-861 service territory, the coverage denominator.
data.denominator.delivery_customers	integer	Of those, the ones buying energy from a competitive supplier. Their wires utility restores their outage, so they are counted there, once.
data.denominator.supplier_duplicates	integer	Customers retail suppliers file for themselves, already counted on their wires utility. Excluded; reported so the exclusion is visible.
data.denominator.eia_year	integer \| null	EIA-861 year of the customer counts.

Example response (illustrative values)

{
  "data": {
    "coverage": {
      "sources": 64,
      "sources_ok": 62,
      "customers_out": 184203,
      "county_level_out": 172153,
      "not_localized_out": 12050,
      "tracked_customers": 98000000
    },
    "feeds": {
      "total": 64,
      "live": 62,
      "stale": 1,
      "down": 1,
      "customers_out_before_dedupe": 196430,
      "oldest_last_ok_ts": "2026-09-14T13:50:00.000Z"
    },
    "connector_coverage": {
      "total_customers": 162000000,
      "county_customers": 70000000,
      "utility_customers": 20000000,
      "outage_only_customers": 50000000,
      "blind_customers": 22000000,
      "eia_year": 2024
    },
    "denominator": {
      "wires_customers": 162000000,
      "delivery_customers": 30000000,
      "supplier_duplicates": 29000000,
      "eia_year": 2024
    }
  }
}

GET/api/v1/live/counties/{fips}

Live status for one county

Customers out, incidents, per-utility breakdown with ETRs, freshness and momentum. Returns zeros (not 404) when nothing is out. `?format=csv` downloads the per-utility breakdown.

Parameter	In	Type	Description
fips*	path	string	5-digit county FIPS code (state + county), e.g. 34025 for Monmouth County, NJ.
format	query	json \| csv	Response format; csv returns the per-utility rows.

200: application/json, text/csv500: Unexpected server error. `request_id` matches the X-Request-Id header.

Response fields (22)

Field	Type	Description
data	object
data.fips	string	5-digit county FIPS.
data.customers_out	integer	Customers without power in the county right now (all live sources).
data.customers_tracked	integer \| null	Customers served by sources that publish a denominator.
data.pct	number \| null	customers_out / customers_tracked × 100, when a denominator exists.
data.incident_count	integer	Active outage incidents.
data.utilities	array	Per-utility breakdown of customers out.
data.utilities[].id	string	Utility identifier as reported by the live feed.
data.utilities[].name	string	Utility name.
data.utilities[].customers_out	integer	Customers out for this utility in the county.
data.utilities[].etr	string \| null	Utility's estimated time of restoration (ISO 8601), the utility's estimate; it changes.
data.worst_etr	string \| null	Latest utility ETR among active outages (ISO 8601).
data.updated_at	string \| null	Time of the poll that produced this rollup. Null when nothing is out.
data.as_of	string \| null	Oldest contributing source's fetch time. Older than updated_at means data is carried forward (stale).
data.trend	object \| null	Outage momentum; null when nothing is out.
data.trend.direction	string enum	Momentum of the current outage. (rising, steady, improving)
data.trend.duration_min	integer	Minutes the current contiguous outage run has lasted.
data.trend.peak_out	integer	Peak customers out during the current run.
data.trend.series	array	Recent samples of the current run, oldest to newest.
data.trend.span_min	integer	Minutes covered by `series`.
data.trend.normalcy	string enum	How this outage compares with the county's history. (routine, elevated, major)
data.trend.vs_record_pct	number \| null	Current customers out as % of this county's worst episode on record.

Example response (illustrative values)

{
  "data": {
    "fips": "34025",
    "customers_out": 1840,
    "customers_tracked": 347000,
    "pct": 0.53,
    "incident_count": 27,
    "utilities": [
      {
        "id": "9726",
        "name": "JCP&L",
        "customers_out": 1620,
        "etr": "2026-09-14T18:00:00.000Z"
      }
    ],
    "worst_etr": "2026-09-14T18:00:00.000Z",
    "updated_at": "2026-09-14T13:50:00.000Z",
    "as_of": "2026-09-14T13:50:00.000Z",
    "trend": {
      "direction": "improving",
      "duration_min": 140,
      "peak_out": 3100,
      "series": [
        3100,
        2800,
        2200,
        1840
      ],
      "span_min": 30,
      "normalcy": "elevated",
      "vs_record_pct": 4.6
    }
  }
}

GET/api/v1/live/counties/{fips}/areas

Live municipalities/townships in a county

Every municipality each utility reports in the county, most affected first, with masked ("<N") outages and ETRs. Only feeds that report areas appear (e.g. NJ PSE&G and JCP&L).

Parameter	In	Type	Description
fips*	path	string	5-digit county FIPS code (state + county), e.g. 34025 for Monmouth County, NJ.
format	query	json \| csv \| geojson	Response format. geojson emits bbox polygons.
utility	query	string	Only rows for this utility: an exact `utility_key` or a case-insensitive substring of the utility name (e.g. `jcp`, `pse&g`).
active	query	boolean, default false	`true` keeps only areas with customers_out > 0 or masked_outages > 0.
min_customers	query	number	Only areas with at least this many customers out. Negative or non-numeric values are ignored.

200: application/json, text/csv, application/geo+json400: Invalid FIPS or format.500: Unexpected server error. `request_id` matches the X-Request-Id header.

Response fields (17)

Field	Type	Description
data	array
data[].utility_key	string	Utility key (use with ?utility=).
data[].utility_name	string	Utility name.
data[].area_type	string	Area type as the utility reports it (e.g. Township, Borough, Municipality).
data[].name	string	Municipality/township name as the utility reports it.
data[].customers_served	integer \| null	Customers the utility serves in this area.
data[].customers_out	integer	Customers out in this area. 0 may still hide masked outages.
data[].masked_outages	integer	Outages the utility reports as "<N" (count hidden for privacy). Unknown size, not zero.
data[].incident_count	integer \| null	Incidents in this area.
data[].pct_out	number \| null	customers_out / customers_served × 100.
data[].etr	string \| null	Utility's estimated restoration for the area (ISO 8601).
data[].bbox	array \| null	[minLon, minLat, maxLon, maxLat].
data[].as_of	string	When the utility's feed was fetched. Rows older than 1 hour are excluded.
as_of	string \| null	Latest feed time across the county's areas (before filters).
meta	object	Notice and echo of applied filters on county detail endpoints.
meta.notice	string	Terms of use for the data; same text as the X-Data-Notice header.
meta.filters	object	The filters that were applied (null/false when not set).

Example response (illustrative values)

{
  "data": [
    {
      "utility_key": "9726",
      "utility_name": "JCP&L",
      "area_type": "Borough",
      "name": "BRIELLE BOROUGH",
      "customers_served": 2678,
      "customers_out": 412,
      "masked_outages": 0,
      "incident_count": 3,
      "pct_out": 15.38,
      "etr": "2026-09-14T18:00:00.000Z",
      "bbox": [
        -74.08,
        40.09,
        -74.04,
        40.12
      ],
      "as_of": "2026-09-14T13:50:00.000Z"
    }
  ],
  "as_of": "2026-09-14T13:50:00.000Z",
  "meta": {
    "notice": "Unofficial aggregate of public utility and government data; confirm with the utility or your OEM before acting. Emergencies: call 911.",
    "filters": {
      "utility": "jcp",
      "active": true,
      "min_customers": null
    }
  }
}

GET/api/v1/live/counties/{fips}/incidents

Live outage incidents in a county

Individual outages with location, customers out, utility ETR, crew status and cause.

Parameter	In	Type	Description
fips*	path	string	5-digit county FIPS code (state + county), e.g. 34025 for Monmouth County, NJ.
format	query	json \| csv \| geojson	Response format. geojson emits points.
utility	query	string	Only rows for this utility: an exact `utility_key` or a case-insensitive substring of the utility name (e.g. `jcp`, `pse&g`).
min_customers	query	number	Only incidents (unknown counts count as 0) with at least this many customers out. Negative or non-numeric values are ignored.

200: application/json, text/csv, application/geo+json400: Invalid FIPS or format.500: Unexpected server error. `request_id` matches the X-Request-Id header.

Response fields (16)

Field	Type	Description
data	array
data[].utility_key	string	Utility key.
data[].utility_name	string	Utility name.
data[].lat	number	Latitude of the outage marker (utility-provided, often approximate).
data[].lon	number	Longitude.
data[].customers_out	integer \| null	Customers out; null when the utility masks the count.
data[].customers_below	integer \| null	Upper bound when the utility reports "<N".
data[].etr	string \| null	Utility's estimated time of restoration (ISO 8601).
data[].crew_status	string \| null	Crew status text as the utility reports it.
data[].cause	string \| null	Cause text as the utility reports it.
data[].started_at	string \| null	When the outage started.
data[].as_of	string	When the utility's feed was fetched.
as_of	string \| null	Latest feed time across the county's incidents (before filters).
meta	object	Notice and echo of applied filters on county detail endpoints.
meta.notice	string	Terms of use for the data; same text as the X-Data-Notice header.
meta.filters	object	The filters that were applied (null/false when not set).

Example response (illustrative values)

{
  "data": [
    {
      "utility_key": "9726",
      "utility_name": "JCP&L",
      "lat": 40.108,
      "lon": -74.057,
      "customers_out": 212,
      "customers_below": null,
      "etr": "2026-09-14T18:00:00.000Z",
      "crew_status": "Crew assigned",
      "cause": "Tree contact",
      "started_at": "2026-09-14T11:32:00.000Z",
      "as_of": "2026-09-14T13:50:00.000Z"
    }
  ],
  "as_of": "2026-09-14T13:50:00.000Z",
  "meta": {
    "notice": "Unofficial aggregate of public utility and government data; confirm with the utility or your OEM before acting. Emergencies: call 911.",
    "filters": {
      "utility": null,
      "min_customers": 100
    }
  }
}

GET/api/v1/live/counties/{fips}/alerts

Threshold alert status for a county

Evaluates your thresholds for the county, each utility (with the 10% major-event line) and each municipality. Utilities without a live feed are listed with `visible: false` and must not be treated as clear.

Parameter	In	Type	Description
fips*	path	string	5-digit county FIPS code (state + county), e.g. 34025 for Monmouth County, NJ.
min_customers	query	number	Customers-out threshold.
min_pct	query	number	Percent-out threshold (0-100). When both are set, both must be crossed.
utility	query	string	Only rows for this utility: an exact `utility_key` or a case-insensitive substring of the utility name (e.g. `jcp`, `pse&g`). Narrows utilities and areas; the county figure stays county-wide.

200: application/json400: Invalid FIPS.500: Unexpected server error. `request_id` matches the X-Request-Id header.

Response fields (31)

Field	Type	Description
data	object
data.fips	string	5-digit county FIPS.
data.thresholds	object
data.thresholds.min_customers	number \| null	Applied min_customers.
data.thresholds.min_pct	number \| null	Applied min_pct.
data.thresholds.major_event_pct	number	Major-event percentage line (10).
data.county	object
data.county.customers_out	integer	County customers out (county-wide, not narrowed by ?utility).
data.county.pct_out	number \| null	Percent of county customers out.
data.county.above_threshold	boolean	Crosses every threshold that was set; false when none is set.
data.utilities	array
data.utilities[].utility_key	string	Utility key.
data.utilities[].name	string	Utility name.
data.utilities[].connector_status	string enum	How MassOutage sees this utility: county = reported by county every poll (0 out is a real all-clear); utility = total only; outage_only = appears only while it has outages; none = no feed. (county, utility, outage_only, none)
data.utilities[].customers_out	integer \| null	Customers out in the county; null when not reported.
data.utilities[].customers_served	integer \| null	Customers served in the county.
data.utilities[].pct_out	number \| null	Percent of the utility's county customers out.
data.utilities[].above_threshold	boolean	Crosses every threshold that was set.
data.utilities[].major_event	boolean	At least 10% of the utility's county customers out (N.J.A.C. 14:5-8.9 line).
data.utilities[].visible	boolean	True only for connector_status county or utility. A non-visible utility can never be reported as clear.
data.areas_above_threshold	array	Municipalities crossing the thresholds, largest first (area rows also carry the other LiveArea fields).
data.areas_above_threshold[].utility_key	string	Utility key.
data.areas_above_threshold[].utility_name	string	Utility name.
data.areas_above_threshold[].name	string	Municipality.
data.areas_above_threshold[].customers_out	integer	Customers out.
data.areas_above_threshold[].customers_served	integer \| null	Customers served.
data.areas_above_threshold[].pct_out	number \| null	Percent out.
data.as_of	string \| null	County live data time.
meta	object	Notice and echo of applied filters on county detail endpoints.
meta.notice	string	Terms of use for the data; same text as the X-Data-Notice header.
meta.filters	object	The filters that were applied (null/false when not set).

Example response (illustrative values)

{
  "data": {
    "fips": "34025",
    "thresholds": {
      "min_customers": 1000,
      "min_pct": null,
      "major_event_pct": 10
    },
    "county": {
      "customers_out": 1840,
      "pct_out": 0.53,
      "above_threshold": true
    },
    "utilities": [
      {
        "utility_key": "9726",
        "name": "Jersey Central Power & Lt Co",
        "connector_status": "county",
        "customers_out": 1620,
        "customers_served": 297055,
        "pct_out": 0.55,
        "above_threshold": true,
        "major_event": false,
        "visible": true
      },
      {
        "utility_key": "15477",
        "name": "Public Service Elec & Gas Co",
        "connector_status": "county",
        "customers_out": 220,
        "customers_served": 1565,
        "pct_out": 14.06,
        "above_threshold": false,
        "major_event": true,
        "visible": true
      }
    ],
    "areas_above_threshold": [],
    "as_of": "2026-09-14T13:50:00.000Z"
  },
  "meta": {
    "notice": "Unofficial aggregate of public utility and government data; confirm with the utility or your OEM before acting. Emergencies: call 911.",
    "filters": {
      "utility": null,
      "min_customers": 1000,
      "min_pct": null
    }
  }
}

History

Historical series and federal disturbance reports.

GET/api/v1/disturbances

DOE OE-417 major electric disturbances

Summary stats and the 100 most recent OE-417 major disturbance reports.

No parameters.

200: application/json500: Unexpected server error. `request_id` matches the X-Request-Id header.

Response fields (25)

Field	Type	Description
data	object
data.stats	object
data.stats.total	integer	Reports on file.
data.stats.years	object
data.stats.years.min	integer \| null	First year.
data.stats.years.max	integer \| null	Last year.
data.stats.total_customers	integer	Customers affected across all reports.
data.stats.by_type	array
data.stats.by_type[].event_type	string	Event type.
data.stats.by_type[].n	integer	Count.
data.recent	array
data.recent[].id	integer	Row id.
data.recent[].began_date	string \| null	Event start.
data.recent[].restored_date	string \| null	Restoration.
data.recent[].event_type	string \| null	OE-417 event type.
data.recent[].nerc_region	string \| null	NERC region.
data.recent[].area_affected	string \| null	Area affected.
data.recent[].demand_loss_mw	number \| null	Demand loss (MW).
data.recent[].customers_affected	integer \| null	Customers affected.
data.recent[].year	integer \| null	Year.
meta	object	Dataset-level provenance. Omitted when there is nothing to report.
meta.sources	array	Datasets this response draws on, for citation.
meta.sources[].name	string	Upstream dataset name.
meta.sources[].url	string	Resolvable URL of the upstream dataset.
meta.last_modified	string \| null	When the underlying data last changed (live poll time on live endpoints).

GET/api/v1/trend/data

Customers-out trend series

Time series for national, state, county or utility scope. `out` is null where the poller had a gap.

Parameter	In	Type	Description
fips	query	string	County scope (5-digit FIPS). Omit all scopes for national.
stateFips	query	string	State scope (2-digit FIPS).
utilityId	query	string	Utility scope (utility key).
range	query	24h \| 7d \| 30d \| 90d \| 12mo	Time window.
region	query	string, default United States	Display label echoed back and used in filenames.
format	query	json \| csv	Response format.

200: application/json, text/csv500: Unexpected server error. `request_id` matches the X-Request-Id header.

Response fields (10)

Field	Type	Description
data	object
data.region	string	Echoed region label.
data.range	string	Applied range.
data.scope	object
data.scope.fips	string \| null	County.
data.scope.stateFips	string \| null	State.
data.scope.utilityId	string \| null	Utility.
data.series	array
data.series[].t	string	Sample time.
data.series[].out	integer \| null	Customers out; null where the poller had a gap.

GET/api/v1/reports/data

Annual report hub tables

Year-over-year national EAGLE-I totals and every state-year. `national` lists every report year from 2015 through the last complete year; years whose EAGLE-I data is not loaded yet have `loaded: false` and null values (a gap, not zero). `coverage_pct` is EAGLE-I's share of customers tracked, weighted by state customers.

Parameter	In	Type	Description
table	query	national \| states	Which report table to return.
format	query	json \| csv	Response format; csv downloads the table.

200: application/json, text/csv400: Unknown table or format.500: Unexpected server error. `request_id` matches the X-Request-Id header.

Response fields (11)

Field	Type	Description
data	object
data.scope	string	Always US.
data.loaded_years	array
data.table	string	Table returned.
data.columns	array	Column order (same as the CSV header).
data.rows	array
meta	object	Dataset-level provenance. Omitted when there is nothing to report.
meta.sources	array	Datasets this response draws on, for citation.
meta.sources[].name	string	Upstream dataset name.
meta.sources[].url	string	Resolvable URL of the upstream dataset.
meta.last_modified	string \| null	When the underlying data last changed (live poll time on live endpoints).

GET/api/v1/reports/{year}/data

National annual report tables

Tables behind /reports/{year}: every county ranked by average hours without power per customer (`counties`, with customer-hours for absolute ranking), the 25 biggest outage episodes (`events`), states with prior-year change and coverage (`states`), month-by-month totals (`months`), reported causes (`causes`, from utility cause reports; shares exclude unreported) and DOE OE-417 filings (`disturbances`).

Parameter	In	Type	Description
year*	path	integer	Report year.
table	query	counties \| events \| states \| months \| causes \| disturbances	Which report table to return.
format	query	json \| csv	Response format; csv downloads the table.

200: application/json, text/csv400: Unknown table or format.404: Year not loaded or not a report year.500: Unexpected server error. `request_id` matches the X-Request-Id header.

Response fields (11)

Field	Type	Description
data	object
data.scope	string	Always US.
data.year	integer	Report year.
data.table	string	Table returned.
data.columns	array	Column order (same as the CSV header).
data.rows	array
meta	object	Dataset-level provenance. Omitted when there is nothing to report.
meta.sources	array	Datasets this response draws on, for citation.
meta.sources[].name	string	Upstream dataset name.
meta.sources[].url	string	Resolvable URL of the upstream dataset.
meta.last_modified	string \| null	When the underlying data last changed (live poll time on live endpoints).

GET/api/v1/reports/{year}/{state}/data

State annual report tables

Tables behind /reports/{year}/{state}: all counties in the state ranked, the state's 25 biggest outage episodes, monthly totals and reported causes.

Parameter	In	Type	Description
year*	path	integer	Report year.
state*	path	string	State slug.
table	query	counties \| events \| months \| causes	Which report table to return.
format	query	json \| csv	Response format; csv downloads the table.

200: application/json, text/csv400: Unknown table or format.404: Unknown state, or year not loaded.500: Unexpected server error. `request_id` matches the X-Request-Id header.

Response fields (12)

Field	Type	Description
data	object
data.scope	string	State abbreviation.
data.state	string	State name.
data.year	integer	Report year.
data.table	string	Table returned.
data.columns	array	Column order (same as the CSV header).
data.rows	array
meta	object	Dataset-level provenance. Omitted when there is nothing to report.
meta.sources	array	Datasets this response draws on, for citation.
meta.sources[].name	string	Upstream dataset name.
meta.sources[].url	string	Resolvable URL of the upstream dataset.
meta.last_modified	string \| null	When the underlying data last changed (live poll time on live endpoints).

GET/api/v1/reports/{year}/{state}/{county}/data

County annual report tables

Tables behind the county annual report: a one-row `summary` (customer-hours, average hours per customer, peak, outage episodes at 100/1,000/10,000+ customers, longest episode, state and national averages, state and national rank, state EAGLE-I coverage), the county's `years` (gaps for years not loaded), `months`, its 10 biggest `events`, reported `causes`, and EIA-861 SAIDI/SAIFI of the `utilities` serving it (report year or nearest earlier filing).

Parameter	In	Type	Description
year*	path	integer	Report year.
state*	path	string	State slug.
county*	path	string	County slug.
table	query	summary \| years \| months \| events \| causes \| utilities	Which report table to return.
format	query	json \| csv	Response format; csv downloads the table.

200: application/json, text/csv400: Unknown table or format.404: Unknown place, year not loaded, or no EAGLE-I data for the county that year.500: Unexpected server error. `request_id` matches the X-Request-Id header.

Response fields (13)

Field	Type	Description
data	object
data.scope	string	County FIPS.
data.county	string	County name.
data.state	string	State abbreviation.
data.year	integer	Report year.
data.table	string	Table returned.
data.columns	array	Column order (same as the CSV header).
data.rows	array
meta	object	Dataset-level provenance. Omitted when there is nothing to report.
meta.sources	array	Datasets this response draws on, for citation.
meta.sources[].name	string	Upstream dataset name.
meta.sources[].url	string	Resolvable URL of the upstream dataset.
meta.last_modified	string \| null	When the underlying data last changed (live poll time on live endpoints).

Events

Outage change events: account-less API and RSS/Atom/JSON feeds, plus the signed webhook contract.

GET/api/v1/events

Outage event stream

Every detected change as an event: outage began, grew (1.5x and at least +250 customers; +50 for municipalities), restoration estimate changed, improving (down 40%), restored (after two polls below half the opening threshold), major event (a utility with 10% or more of its customers out statewide or in a county, the NJ BPU N.J.A.C. 14:5-8.9 line) and data feed stale/recovered. Outages open at the larger of a floor and a share of customers served: counties 500 or 1%, municipalities 50 or 5%, utilities statewide 1,000 or 0.5%. While a subject's feed is stale it is held open and no restored event is emitted. No account needed. Poll with `?after=<next_cursor>` (oldest-first) every 30-60 seconds; without `after` results are newest-first. Events are kept 90 days. The same events drive signed webhooks and Slack/Teams/Discord/email alerts from a free account; see `webhooks`.

Parameter	In	Type	Description
after	query	integer	Cursor: events with id greater than this, oldest-first.
fips	query	string	Comma-separated 5-digit county FIPS codes.
state	query	string	Comma-separated 2-digit state FIPS codes.
utility	query	string	Comma-separated utility keys (exact).
kind	query	string	Comma-separated event kinds: outage_began, outage_grew, etr_changed, outage_improving, outage_restored, major_event, feed_stale, feed_recovered.
min_customers	query	number	Only events with at least this many customers out.
since	query	string	Only events at or after this ISO 8601 time.
limit	query	integer, default 100	Page size (1-1000).

200: application/json400: Invalid filter.500: Unexpected server error. `request_id` matches the X-Request-Id header.

Response fields (23)

Field	Type	Description
data	array
data[].id	integer	Event id; increases monotonically. Use it as the `after` cursor.
data[].ts	string	When the change was detected (poll time).
data[].kind	string enum	What changed. (outage_began, outage_grew, etr_changed, outage_improving, outage_restored, major_event, feed_stale, feed_recovered)
data[].scope	string enum	What the event is about: a county, a municipality as a utility reports it, a utility (statewide, or in one county when `fips` is set), or a data source. (county, municipality, utility, source)
data[].fips	string \| null	5-digit county FIPS.
data[].state_fips	string \| null	2-digit state FIPS.
data[].utility_key	string \| null	Utility key (EIA id where known).
data[].utility_name	string \| null	Utility name.
data[].area_name	string \| null	Municipality name as the utility reports it (scope municipality).
data[].source	string \| null	Live source id (scope source, or the single source behind the reading).
data[].customers_out	integer \| null	Customers out at the time of the event.
data[].customers_served	integer \| null	Customers served by the subject (denominator), when known.
data[].pct	number \| null	Percent of customers served that are out.
data[].etr	string \| null	Earliest utility estimated restoration time. The utility's estimate; it changes.
data[].prev	object \| null	Previously notified values (`customers_out`, `etr`) on change events.
data[].data	object \| null	Context: `county_name`, `state_abbr`, `url`, `opened_at`, `duration_min` and `peak_out` (restored), `major_event`, `utilities` (county scope), `source_name` and `last_ok_ts` (feed events).
data[].title	string	Human-readable title, e.g. `Outage began · Brielle Borough, Monmouth County NJ`.
data[].summary	string	Facts line: utility, customers out, ETR or duration.
data[].url	string	Page for the place on massoutage.com.
next_cursor	integer	Pass as `after` on the next request to receive only newer events.
has_more	boolean	With `after`: true when the page was full and more events are waiting.
latest_id	integer \| null	Highest event id overall (ignores filters).

Example response (illustrative values)

{
  "data": [
    {
      "id": 48213,
      "ts": "2026-09-14T13:50:00.000Z",
      "kind": "outage_began",
      "scope": "municipality",
      "fips": "34025",
      "state_fips": "34",
      "utility_key": "9726",
      "utility_name": "JCP&L",
      "area_name": "BRIELLE BOROUGH",
      "source": "jcpl-34",
      "customers_out": 2000,
      "customers_served": 2678,
      "pct": 74.68,
      "etr": "2026-09-14T22:00:00.000Z",
      "prev": null,
      "data": {
        "subject": "area:9726:34025:BRIELLE BOROUGH",
        "county_name": "Monmouth County",
        "state_abbr": "NJ",
        "url": "/new-jersey/monmouth-county",
        "opened_at": "2026-09-14T13:50:00.000Z",
        "major_event": false
      },
      "title": "Outage began · Brielle Borough, Monmouth County NJ",
      "summary": "JCP&L · 2,000 out (74.7%) · ETR 6:00 PM ET",
      "url": "https://massoutage.com/new-jersey/monmouth-county"
    }
  ],
  "next_cursor": 48213,
  "has_more": false,
  "latest_id": 48213
}

GET/feeds/events.json

Outage events as JSON Feed 1.1

The event stream as a JSON Feed 1.1 feed (newest 50 by default) for feed readers, Slack/Teams RSS apps and EOC tools. Same filters as /api/v1/events except `after`; cached for 60 seconds. Item titles are human-readable and link to the county page. One outage is one item: the county entry carries the utility, town and statewide entries for the same outage in its text and, in the JSON feed, in `_massoutage.related` (each is still its own event in /api/v1/events).

Parameter	In	Type	Description
fips	query	string	Comma-separated 5-digit county FIPS codes.
state	query	string	Comma-separated 2-digit state FIPS codes.
utility	query	string	Comma-separated utility keys (exact).
kind	query	string	Comma-separated event kinds: outage_began, outage_grew, etr_changed, outage_improving, outage_restored, major_event, feed_stale, feed_recovered.
min_customers	query	number	Only events with at least this many customers out.
since	query	string	Only events at or after this ISO 8601 time.
limit	query	integer, default 50	Items (1-1000).

200: application/feed+json400: Invalid filter.

GET/feeds/events.rss

Outage events as RSS 2.0

The event stream as a RSS 2.0 feed (newest 50 by default) for feed readers, Slack/Teams RSS apps and EOC tools. Same filters as /api/v1/events except `after`; cached for 60 seconds. Item titles are human-readable and link to the county page. One outage is one item: the county entry carries the utility, town and statewide entries for the same outage in its text and, in the JSON feed, in `_massoutage.related` (each is still its own event in /api/v1/events).

Parameter	In	Type	Description
fips	query	string	Comma-separated 5-digit county FIPS codes.
state	query	string	Comma-separated 2-digit state FIPS codes.
utility	query	string	Comma-separated utility keys (exact).
kind	query	string	Comma-separated event kinds: outage_began, outage_grew, etr_changed, outage_improving, outage_restored, major_event, feed_stale, feed_recovered.
min_customers	query	number	Only events with at least this many customers out.
since	query	string	Only events at or after this ISO 8601 time.
limit	query	integer, default 50	Items (1-1000).

200: application/rss+xml400: Invalid filter.

GET/feeds/events.atom

Outage events as Atom

The event stream as a Atom feed (newest 50 by default) for feed readers, Slack/Teams RSS apps and EOC tools. Same filters as /api/v1/events except `after`; cached for 60 seconds. Item titles are human-readable and link to the county page. One outage is one item: the county entry carries the utility, town and statewide entries for the same outage in its text and, in the JSON feed, in `_massoutage.related` (each is still its own event in /api/v1/events).

Parameter	In	Type	Description
fips	query	string	Comma-separated 5-digit county FIPS codes.
state	query	string	Comma-separated 2-digit state FIPS codes.
utility	query	string	Comma-separated utility keys (exact).
kind	query	string	Comma-separated event kinds: outage_began, outage_grew, etr_changed, outage_improving, outage_restored, major_event, feed_stale, feed_recovered.
min_customers	query	number	Only events with at least this many customers out.
since	query	string	Only events at or after this ISO 8601 time.
limit	query	integer, default 50	Items (1-1000).

200: application/atom+xml400: Invalid filter.

Charts

Branded PNG charts.

GET/api/v1/counties/{fips}/chart/{type}

County chart PNG

Branded chart image for embedding or download (1200×630, rendered before responding, cached 5 minutes).

Parameter	In	Type	Description
fips*	path	string	5-digit county FIPS code (state + county), e.g. 34025 for Monmouth County, NJ.
type*	path	decade \| monthly \| live \| causes	Chart type.
theme	query	dark \| light	Chart color scheme.
format	query	png \| csv \| json	png renders the chart; csv and json return exactly the plotted series.

200: image/png, text/csv404: Unknown county or chart type (plain text).

GET/api/v1/trend/chart

Trend chart PNG

Branded PNG of the trend series (peak per interval, gaps left empty), stamped with its data-as-of time.

Parameter	In	Type	Description
fips	query	string	County scope (5-digit FIPS). Omit all scopes for national.
stateFips	query	string	State scope (2-digit FIPS).
utilityId	query	string	Utility scope (utility key).
range	query	24h \| 7d \| 30d \| 90d \| 12mo	Time window.
region	query	string, default United States	Display label echoed back and used in filenames.
theme	query	dark \| light	Chart color scheme.
format	query	png \| csv \| json	png renders the chart; csv and json return exactly the plotted series.

200: image/png, text/csv

GET/api/v1/reports/{year}/chart

National annual report chart PNG

Decade trend of average hours without power per customer, the year highlighted.

Parameter	In	Type	Description
year*	path	integer	Report year.
theme	query	dark \| light	Chart color scheme.
format	query	png \| csv \| json	png renders the chart; csv and json return exactly the plotted series.
highlight	query	string	Bar to highlight: a year, max (worst year) or none. Defaults to the report year.

200: image/png, text/csv404: No report for that year (plain text).

GET/api/v1/reports/{year}/{state}/chart

State annual report chart PNG

Decade trend for one state, the year highlighted.

Parameter	In	Type	Description
year*	path	integer	Report year.
state*	path	string	State slug.
theme	query	dark \| light	Chart color scheme.
format	query	png \| csv \| json	png renders the chart; csv and json return exactly the plotted series.
highlight	query	string	Bar to highlight: a year, max (worst year) or none. Defaults to the report year.

200: image/png, text/csv404: Unknown state or year (plain text).

MassOutage API

Counties

County profile: live snapshot + yearly history

County monthly history and worst events

County outage-cause mix

Live

National and per-state live totals

Compact severity map of every county and state out

Ranked live leaders

State severity timeline

Feed health and coverage (status endpoint)

Live status for one county

Live municipalities/townships in a county

Live outage incidents in a county

Threshold alert status for a county

History

DOE OE-417 major electric disturbances

Customers-out trend series

Annual report hub tables

National annual report tables

State annual report tables

County annual report tables

Events

Outage event stream

Outage events as JSON Feed 1.1

Outage events as RSS 2.0

Outage events as Atom

Charts

County chart PNG

Trend chart PNG

National annual report chart PNG

State annual report chart PNG

Meta

This OpenAPI document