Causes

Networks describe causes in wildly different ways. One writes a clause ("upgrading power poles in your area"), another a whole sentence ("The loss of supply is due to a bush fire."), another a label ("Bird/Bat"), and some write nothing at all. Every outage's cause therefore carries two things:

cause.category — one value from a single vocabulary, the same for every network, so "how many outages did vegetation cause in Queensland last month" has an answer.
cause.description — the network's own words, verbatim.

Filter by category with cause= on GET/v1/outages and GET/v1/stats/outages, comma-separated.

The categories

Category	Means	Network text that lands here
`planned_work`	Maintenance, upgrades, connections, metering	“trimming trees to ensure reliable power for your neighbourhood” “an unforeseen issue that has prevented the work from being carried out”
`weather`	Storms, lightning, wind, flood, heat	“severe weather conditions” “Storm activity” “Lightning” “Wind damage”
`vegetation`	Trees and branches in or on the lines	“Trees on powerlines” “Wind (Growing or falling tree or branches not felled or lopped - bark, grass)” “Vegetation contact with our equipment”
`animal`	Birds, bats, possums, wildlife	“Bird/Bat” “Wildlife in wires” “The loss of supply is due to damage caused by external influences, such as birds or animals.”
`vehicle`	A car, truck or high load hitting the network	“A vehicle damaging our equipment” “Vehicle High Load”
`third_party`	Vandalism, theft, dig-ins, other people's works	“Third party asset damage” “Vandalism” “The loss of supply is due to damage caused by accidental contact with powerlines by a third party.”
`fire`	Bushfire or fire near the network	“The loss of supply is due to a bush fire.”
`equipment`	A failure of the network's own poles, wires, cables or plant	“Network equipment fault” “Due to an underground cable fault” “Wear & Tear” “Wires down”
`customer`	A fault in the customer's installation, or work they asked for	“Fault Within Customer Installation” “customer equipment fault” “Customer works”
`safety`	Supply cut for public safety or at emergency services' request	“Power interrupted for safety reasons” “The loss of supply is due to public safety concerns as directed by emergency services.”
`upstream`	Transmission or generation, outside the distributor's network	“ElectraNet maintenance on its transmission network”
`unspecified`	A fault, with no cause given yet	“Under investigation” “Emergency Repairs” “Cause Unknown” “None” “Crews inspecting”
`other`	A cause the classifier does not recognise yet	“Providing safe access for contractors”

Every phrase above is real network text from the archive, and each is a test case the classifier must keep getting right.

The rules

Planned work is always planned_work, whatever its text says. The text of a planned outage describes what the crew is doing — metering, poles, tree trimming — not what went wrong, because nothing did. Filing scheduled tree trimming under vegetation would put pruning in the same bucket as a gum tree through the lines, which is the one mix-up a reliability analysis cannot undo. To find vegetation-related work, read cause.description on planned outages.

For a fault, the most specific cause named wins. "A vehicle damaging our equipment" is vehicle, not equipment. "Wind (Growing or falling tree…)" is vegetation, not weather. "Fault Within Customer Installation" is customer, not equipment. Specific causes are checked before general ones, because almost every fault description mentions damage or a fault somewhere.

Three different absences, three different answers:

`cause.category`	When	Means
`unspecified`	The network wrote something that names no cause: "Under investigation", "Emergency Repairs", "Cause Unknown", a literal "None", or status words in the cause field.	A fault happened, and the network has not said why. A real, countable answer.
`other`	The network named a cause the classifier does not recognise yet.	Something specific, not yet in the vocabulary. Each distinct `other` text is reported to us and reviewed.
`null`	The network published no cause text at all.	Absent. Some networks never fill the field.

Count unspecified and null separately: "the network did not say why" and "this network never says" are different facts. GET/v1/networks gives each network's publishes.cause share, so you can see which networks are which.

Categories can change underneath an outage

A network often updates its cause text as a fault is investigated — "Under investigation" becoming "Vegetation contact with our equipment" — and the category follows the text. When the classifier itself improves, past outages are reclassified so the archive stays consistent. Neither changes an outage's id. New categories may be added within /v1; treat a value you do not recognise as other.