Statuses

Every network describes an outage's progress in its own words — Outage Reported, Crews on site, AWAITING CONSTRUCTION, Partially Restored. The API maps them all onto five statuses, and keeps the network's words in status_detail.

Cancelled is never restored

A cancelled planned shutdown is not an outage that was fixed — it is one that never happened, and for anyone who planned around it (hiring a generator, rescheduling a shift) it is the thing they most need to know. So cancelled is its own status, it has no restored_at, and it is never summed with restored. GET/v1/stats/outages leaves it out of every total, and active_at never matches it.

Not every network publishes a cancellation. Where a network simply removes cancelled work from its feed, the API cannot tell that apart from work that finished, and records it as restored with restored_at_basis: observed. Networks and coverage notes which networks these are.

How a network's words become a status

The mapping lives with each network's adapter, because only the adapter knows that one network's DELAYED|Pre-Arranged is planned work that has not begun. Two rules apply to all of them:

• An unrecognised status word means active, never unknown. A word we have not seen before is most often a network's newest, least assessed and most urgent record — a fault just reported. Hiding it would be the wrong side to err on. The network's words are kept in status_detail either way.
• Every unrecognised word is reported to us, so a new phrase in a feed is mapped deliberately rather than left to the fallback.

That is why unknown is so rare: it is reserved for a record that carries no status signal at all, and no network uses it as a fallback.

Where presence is the status

Some feeds publish no status field — they list current outages and nothing else. For them, being in the feed is the evidence that supply is affected, so a listed outage is active and it becomes restored when it leaves the feed. Others publish months of forward and cancelled work, and their status fields have to be read closely. Either way the result is the same five statuses.

Counting

• What is off now: filter status=active, sum customers_off_now.
• What happened: restored outages, by starts_at or restored_at.
• What was planned and called off: cancelled, on its own.
• Never add cancelled to restored, and never count scheduled as an outage that has happened.