Places and attribution

"Was this outage in Cranbourne?" sounds like one question and is answered differently by different feeds. Some list the affected towns with their postcodes; some list towns without postcodes; some list nothing and publish a shape; some publish only a point. The API answers it with one rule, used everywhere — the suburb filter, the suburbs on an outage, and the suburb pages on the public site — so a suburb's figures never disagree with its own list of outages.

The rule

The network's words where they exist, the shape where they do not.

An outage belongs to a suburb when either:

The network named it. The outage lists at least one locality with both a town and a postcode, and one of them is this suburb — by town and postcode together, or by town alone where the outage's own shape reaches the suburb and the network operates in the suburb's state.
The network named nothing usable, and the shape reaches it. The outage lists no locality with a town and a postcode, and its shape intersects the suburb.

Each outage uses one branch or the other, never both, so nothing is counted twice.

Why a town needs a postcode

A bare name is not enough: there is a Richmond in three states and a Springfield in four. A town without a postcode could file a Queensland fault under a Victorian suburb. Feeds that give a town without a postcode fall to the shape branch instead, and they all publish real shapes.

Why the network's words come first

Because for the largest feed in the archive the shape is the weaker evidence. AusNet publishes an approximate point for each outage, and its own list of affected towns says far more reliably who lost supply than a point we already tell readers not to trust.

Why the state check

A town name matched across a state border is the one way a name match goes wrong. A Victorian network listing a small Murray River locality whose namesake sits on the New South Wales bank would otherwise place a Victorian outage on a New South Wales suburb page. Requiring the network to operate in the suburb's state stops it.

The place filters

Filter	Matches	Use it for
`suburb`	The rule above, by suburb `id` from GET`/v1/suburbs`.	"Outages in this suburb." Works for every network.
`postcode`	Outages whose network listed this postcode.	The network's own postcode list. Networks that publish no postcodes never match.
`near` + `radius_km`	Outages whose area or point lies within `radius_km` of a point. `0` means the point must be inside the area.	An address. See Was the power out at this address.
`bbox`	Outages whose area or point falls inside `minLng,minLat,maxLng,maxLat`.	A map view.
`state`	The state the outage is in, from its location.	A state, including across-border outages.

near takes lat,lng — latitude first — and must be inside Australia. bbox takes longitude first, the GeoJSON order, and may cover up to 400 square degrees; for anything larger, filter by state.

Suburbs

GET/v1/suburbs lists every suburb in every covered state — not only the ones that have had an outage — with a stable id, its postcode and state, the networks that serve it where known, and the url of its page on the public site. Look ids up once and keep them.

A suburb's networks can be empty. Coverage is known from each network's published boundary where there is one; for networks without a boundary it is learned from the outages they publish, and grows as the archive does.