# EmergencyAPI API Reference

Base URL: `https://emergencyapi.com/api/v1`

Real-time Australian emergency incident data from official government feeds across all 8 states and territories, unified into a single REST API.

## Endpoints

### GET /incidents

List all current incidents

Returns a GeoJSON FeatureCollection of all current emergency incidents, with support for filtering, pagination, and bounding box queries.

Parameters:

| Name | In | Required | Type | Description |
| --- | --- | --- | --- | --- |
| `state` | query | no | `string` | Comma-separated state codes (e.g. nsw,vic,qld) |
| `eventType` | query | no | `string` | Comma-separated event types (bushfire, burn_off, fire_ban, structure_fire, vehicle_fire, grass_fire, hazmat, rescue, flood, storm, tree_down, cyclone, earthquake, extreme_heat, vehicle_accident, medical, alarm, other) |
| `category` | query | no | `string` | Comma-separated event categories. Groups related event types (e.g. fire includes bushfire, structure_fire, grass_fire, vehicle_fire). burn_off is its own category (planned). See /api/v1/schema for the full mapping. |
| `featureType` | query | no | `string` | Comma-separated feature types. Defaults to 'incident' (point incidents only), so boundary polygons never appear unless requested. Request them explicitly: incident_area, warning_area, fire_ban_area. See /api/v1/schema. |
| `severity` | query | no | `string` | CAP-AU severity levels (Extreme, Severe, Moderate, Minor, Unknown) |
| `urgency` | query | no | `string` | CAP-AU urgency levels (Immediate, Expected, Future, Past, Unknown) |
| `certainty` | query | no | `string` | CAP-AU certainty levels (Observed, Likely, Possible, Unlikely, Unknown) |
| `warningLevel` | query | no | `string` | Australian Warning System levels |
| `status` | query | no | `string` | Incident status filter |
| `agency` | query | no | `string` | Source agency filter |
| `bbox` | query | no | `string` | Bounding box: minLon,minLat,maxLon,maxLat |
| `limit` | query | no | `integer` | Results per page (default 100, max 500) |
| `after` | query | no | `string` | Cursor for pagination (from meta.next_cursor) |
| `format` | query | no | `string` | Response format. CSV includes columns: id, state, agency, feed_id, title, event_type, status, warning_level, severity, urgency, certainty, lng, lat, address, suburb, lga, location_state, reported_at, updated_at, fetched_at, is_retracted, retracted_at, retraction_reason. cap-atom returns a standards-validated CAP Atom feed (each entry inlines a CAP-AU alert in <content>; incidents retracted in the last 7 days appear as Cancel messages). cap-au is the deprecated legacy <alerts> wrapper, kept for backward compatibility; new consumers should use cap-atom. |
| `include_retracted` | query | no | `boolean` | Include retracted incidents (default false). Retracted incidents are marked when upstream feeds stop publishing them. |

Responses:

| Status | Description |
| --- | --- |
| `200` | A GeoJSON FeatureCollection of incidents |
| `429` | Rate limit exceeded |

Example request:

```bash
curl "https://emergencyapi.com/api/v1/incidents?state=nsw%2Cvic&eventType=bushfire%2Cflood" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

Example response:

```json
{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "id": "nsw-rfs-1234567",
      "geometry": {
        "type": "Point",
        "coordinates": [
          150.604,
          -33.883
        ]
      },
      "properties": {
        "source": {
          "state": "nsw",
          "agency": "RFS",
          "feedId": "1234567"
        },
        "title": "Bush Fire - Warragamba",
        "eventType": "bushfire",
        "status": "active",
        "warningLevel": "watch_and_act",
        "severity": "Severe",
        "urgency": "Expected",
        "certainty": "Observed",
        "location": {
          "address": "Warragamba Dam Rd, Warragamba NSW",
          "suburb": "Warragamba",
          "state": "NSW",
          "latitude": -33.883,
          "longitude": 150.604
        },
        "details": {
          "description": "Bush fire burning in a south-easterly direction"
        },
        "timestamps": {
          "reported": "2026-04-07T14:30:00+10:00",
          "updated": "2026-04-07T16:45:00+10:00",
          "fetched": "2026-04-07T16:46:12+10:00"
        },
        "retraction": {
          "retracted": true,
          "retractedAt": "2026-04-07T18:00:00+10:00",
          "reason": "upstream_removed"
        }
      }
    }
  ],
  "meta": {
    "total_count": 245,
    "has_more": true,
    "next_cursor": "cursor_xyz789",
    "generatedAt": "2026-04-07T16:46:12+10:00"
  },
  "links": {
    "self": "/v1/incidents?limit=100",
    "next": "/v1/incidents?limit=100&after=cursor_xyz789"
  },
  "attribution": "https://emergencyapi.com/api/v1/attribution"
}
```

### GET /incidents/{id}

Get a single incident

Returns a single incident as a GeoJSON Feature.

Parameters:

| Name | In | Required | Type | Description |
| --- | --- | --- | --- | --- |
| `id` | path | yes | `string` | Incident ID (e.g. nsw-rfs-1234567) |
| `format` | query | no | `string` | Response format. Default geojson returns a GeoJSON Feature. cap-au returns the incident as a single standards-valid CAP-AU <alert> document (Content-Type application/cap+xml), validated against the OASIS CAP 1.2 schema and the CAP-AU Profile v3.0. |

Responses:

| Status | Description |
| --- | --- |
| `200` | A GeoJSON Feature, or a CAP-AU alert document when format=cap-au |
| `404` | Incident not found |

Example request:

```bash
curl "https://emergencyapi.com/api/v1/incidents/{id}" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

### GET /incidents/nearby

Find incidents near a location

Returns incidents within a radius (km) of a given lat/lng coordinate, sorted by distance.

Parameters:

| Name | In | Required | Type | Description |
| --- | --- | --- | --- | --- |
| `lat` | query | yes | `number` | Latitude |
| `lng` | query | yes | `number` | Longitude |
| `radius` | query | yes | `number` | Radius in kilometres (max 500) |
| `limit` | query | no | `integer` |  |
| `state` | query | no | `string` |  |
| `eventType` | query | no | `string` |  |
| `severity` | query | no | `string` |  |
| `eventCategory` | query | no | `string` |  |
| `urgency` | query | no | `string` |  |
| `certainty` | query | no | `string` |  |
| `warningLevel` | query | no | `string` |  |
| `agency` | query | no | `string` |  |
| `status` | query | no | `string` | Comma-separated incident statuses (active, contained, controlled, safe, completed). Defaults to all. |
| `include_retracted` | query | no | `boolean` | Set true to include retracted incidents. Default false; retracted incidents are hidden, matching /incidents. |

Responses:

| Status | Description |
| --- | --- |
| `200` | Nearby incidents as GeoJSON FeatureCollection |
| `400` | Missing or invalid parameters |

Example request:

```bash
curl "https://emergencyapi.com/api/v1/incidents/nearby?lat=-33.87&lng=151.21" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

### GET /incidents/snapshot

Audit trail snapshot

Returns the incidents that were active at a specific point in time. Recent datetimes are reconstructed from live and lifecycle data. Datetimes before 2026-04-08 are reconstructed from the historical archive (4.8M+ records) and are gated by the same tier lookback as /incidents/history (free has no archive access; Starter 1 year, Developer and Business 5 years, Pro and Enterprise unlimited). Archive (pre-2026-04-08) snapshots require a state filter, and meta.source indicates whether the result came from "live" or "archive".

Parameters:

| Name | In | Required | Type | Description |
| --- | --- | --- | --- | --- |
| `datetime` | query | yes | `string` | ISO 8601 datetime to query (cannot be in the future) |
| `state` | query | no | `string` | Filter by state code. Required for archive (pre-2026-04-08) snapshots. |
| `event_type` | query | no | `string` | Filter by event type |
| `limit` | query | no | `integer` | Max results (default 500) |

Responses:

| Status | Description |
| --- | --- |
| `200` | Incidents active at the requested datetime |
| `400` | Missing or invalid datetime, or an archive (pre-2026-04-08) snapshot requested without the required state filter |
| `403` | Archive access requires a paid plan, or the datetime predates your tier's lookback window |

Example request:

```bash
curl "https://emergencyapi.com/api/v1/incidents/snapshot?datetime=2026-04-20T14%3A30%3A00%2B09%3A30&state=sa" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

### GET /incidents/history

Historical incident data (paid tier)

Returns historical emergency incidents from the 4.8M+ record archive (1840-2026). Free tier is blocked. Starter tier limited to 1 year lookback, Developer and Business to 5 years, Pro and Enterprise unlimited.

Parameters:

| Name | In | Required | Type | Description |
| --- | --- | --- | --- | --- |
| `state` | query | no | `string` | Comma-separated state codes |
| `eventType` | query | no | `string` | Comma-separated event types |
| `after` | query | no | `string` | Start of date range (ISO 8601, inclusive). Tier-limited. |
| `before` | query | no | `string` | End of date range (ISO 8601, exclusive). Defaults to now. |
| `limit` | query | no | `integer` | Max results per page (1-500, default 100) |

Responses:

| Status | Description |
| --- | --- |
| `200` | Historical incidents matching filters |
| `403` | Free tier blocked or depth limit exceeded |

Example request:

```bash
curl "https://emergencyapi.com/api/v1/incidents/history?state=wa%2Csa&eventType=bushfire%2Cflood" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

### GET /states

Feed health by state

Returns the status of each state feed, including last poll time, health, and incident count.

Responses:

| Status | Description |
| --- | --- |
| `200` | Feed status for all states |

Example request:

```bash
curl "https://emergencyapi.com/api/v1/states" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

### GET /declarations/postcode/{postcode}

Disaster declaration status for a postcode

Returns the declaration STATUS for a postcode: declared, partial, activation_only, not_declared, uncertain, or unknown_postcode, with per-LGA detail and official source links. Reports declared-area status only; the billing/eligibility decision rests with the practitioner. Built for Medicare disaster telehealth checks.

Parameters:

| Name | In | Required | Type | Description |
| --- | --- | --- | --- | --- |
| `postcode` | path | yes | `string` |  |
| `as_at` | query | no | `string` | Point-in-time check (YYYY-MM-DD). Defaults to today. |
| `include_expired` | query | no | `boolean` | Include expired records in the per-LGA lists. Never changes matchStatus. |
| `instrument_type` | query | no | `string` | Trim the returned record lists to one instrument type. Never changes matchStatus. |
| `suburb` | query | no | `string` | Optional suburb/locality name (ABS SAL) to narrow the result to the local government areas that suburb falls in, within this postcode only. Matching is exact after normalisation; there is no fuzzy matching. An unmatched suburb never fails the lookup: the full-postcode result is returned with narrowing.applied=false, a reason, and the postcode's known suburbs. Narrowing can legitimately change matchStatus (for example partial to declared); a suburb that itself spans two LGAs stays partial, and a bare name that denotes suburbs on both sides of a border (Mingoola in 4380) matches all of them. |

Responses:

| Status | Description |
| --- | --- |
| `200` | Declaration status (including unknown_postcode for an absent postcode) |
| `400` | Malformed postcode or as_at |
| `401` | Missing or invalid API key |
| `403` | The account lacks the declarations entitlement (enterprise-only, manually negotiated) |
| `429` | Rate limit exceeded |

Example request:

```bash
curl "https://emergencyapi.com/api/v1/declarations/postcode/4380?suburb=Stanthorpe" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

### POST /declarations/point

Disaster declaration status for an exact point

Returns the declaration STATUS for the local government area containing a lat/lng point, resolved against ABS LGA 2022 (ASGS Edition 3) boundary polygons at full resolution. POST with a JSON body is used deliberately so coordinates never appear in URLs or request logs; the request is read-only and safe to retry. Coordinates are never stored, logged, or echoed back, and the response is Cache-Control: no-store. Reports declared-area status only; the billing decision rests with the practitioner. A point outside every Australian LGA returns unknown_location. A point exactly on a shared LGA boundary returns every covering area with onBoundary=true. LGA matching is at ABS code level; some ABS codes aggregate multiple administrative areas (for example Unincorporated NSW covers both Far West and Lord Howe Island).

Responses:

| Status | Description |
| --- | --- |
| `200` | Declaration status for the covering LGA (including unknown_location when no LGA covers the point) |
| `400` | Invalid body, lat, lng, or as_at. Error detail never repeats submitted values. |
| `401` | Missing or invalid API key |
| `403` | The account lacks the declarations entitlement (enterprise-only, manually negotiated) |
| `429` | Rate limit exceeded |

Example request:

```bash
curl "https://emergencyapi.com/api/v1/declarations/point" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

### GET /declarations

List/filter declarations

Browse and historically report on declaration records. Filters and keyset (cursor) pagination. Record status is derived at query time.

Parameters:

| Name | In | Required | Type | Description |
| --- | --- | --- | --- | --- |
| `jurisdiction` | query | no | `string` |  |
| `status` | query | no | `string` |  |
| `instrument_type` | query | no | `string` |  |
| `disaster_type` | query | no | `string` |  |
| `active_on` | query | no | `string` |  |
| `limit` | query | no | `integer` |  |
| `cursor` | query | no | `string` | Opaque pagination cursor from links.next. |

Responses:

| Status | Description |
| --- | --- |
| `200` | A page of declaration records |
| `400` | Invalid active_on date, status, limit, or cursor |
| `401` | Missing or invalid API key |
| `403` | The account lacks the declarations entitlement (enterprise-only, manually negotiated) |
| `429` | Rate limit exceeded |

Example request:

```bash
curl "https://emergencyapi.com/api/v1/declarations" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

### GET /declarations/agrn/{agrn}

One disaster event by AGRN (across sources)

The declaration/activation for an Australian Government Reference Number, merged across sources with the full affected-LGA list.

Parameters:

| Name | In | Required | Type | Description |
| --- | --- | --- | --- | --- |
| `agrn` | path | yes | `string` |  |

Responses:

| Status | Description |
| --- | --- |
| `200` | The merged declaration record |
| `400` | Malformed AGRN (must be numeric) |
| `401` | Missing or invalid API key |
| `403` | The account lacks the declarations entitlement (enterprise-only, manually negotiated) |
| `404` | No declaration found for the AGRN |
| `429` | Rate limit exceeded |

Example request:

```bash
curl "https://emergencyapi.com/api/v1/declarations/agrn/1284" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

### GET /status

API health check

Returns API health, version, uptime, and a summary of feed statuses.

Responses:

| Status | Description |
| --- | --- |
| `200` | API health status |

Example request:

```bash
curl "https://emergencyapi.com/api/v1/status"
```

### GET /attribution

Data source attributions

Returns attribution information for all data sources, including licence details. Required for CC BY compliance.

Responses:

| Status | Description |
| --- | --- |
| `200` | Attribution data for all sources |

Example request:

```bash
curl "https://emergencyapi.com/api/v1/attribution"
```

### GET /events

List clustered events (incident intelligence)

Returns spatially clustered emergency events as a GeoJSON FeatureCollection.
Events group related incidents using PostGIS ST_ClusterDBSCAN spatial clustering.
Each event has a boundary polygon, centroid, affected suburbs, contributing agencies,
and auto-generated title and summary. Only active events are returned by default.


Parameters:

| Name | In | Required | Type | Description |
| --- | --- | --- | --- | --- |
| `limit` | query | no | `integer` | Maximum events to return (default 50, max 200) |
| `state` | query | no | `string` | Comma-separated state codes to filter by (e.g. nsw,vic). Uses array overlap matching. |
| `eventType` | query | no | `string` | Comma-separated event types (e.g. bushfire,flood) |
| `severity` | query | no | `string` | Comma-separated max severity levels |
| `warningLevel` | query | no | `string` | Comma-separated max warning levels |

Responses:

| Status | Description |
| --- | --- |
| `200` | A GeoJSON FeatureCollection of clustered events |
| `401` | Missing or invalid API key |
| `429` | Rate limit exceeded |

Example request:

```bash
curl "https://emergencyapi.com/api/v1/events?state=nsw%2Cvic&eventType=bushfire%2Cflood" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

### GET /events/{id}

Get a single event with optional linked incidents

Returns a single clustered event by ID. Use `include_incidents=true` to also
retrieve all incidents that belong to this event cluster.


Parameters:

| Name | In | Required | Type | Description |
| --- | --- | --- | --- | --- |
| `id` | path | yes | `string` | Event UUID |
| `include_incidents` | query | no | `boolean` | Include linked incidents in the response |

Responses:

| Status | Description |
| --- | --- |
| `200` | A single event as a GeoJSON Feature |
| `401` | Missing or invalid API key |
| `404` | Event not found |

Example request:

```bash
curl "https://emergencyapi.com/api/v1/events/{id}" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

### GET /schema

API schema and valid enum values

Returns all valid enum values for event types, categories, states, warning levels, and other filterable fields. Use this to discover what values are accepted by filter parameters. No authentication required.

Responses:

| Status | Description |
| --- | --- |
| `200` | All valid enum values and category mappings |

Example request:

```bash
curl "https://emergencyapi.com/api/v1/schema" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

### GET /gauges

River gauge stations with live flood status

Returns river gauge stations with their latest water level, the Bureau of Meteorology flood classification thresholds for each gauge, and a derived floodClass (below_minor, minor, moderate, major, or unclassified) computed from the latest reading against the published thresholds. Readings are in metres relative to each gauge's local datum. readingStatus flags stale data (bom-kiwis sourced stations are a 1-2 day archive, stale horizon 72 hours; telemetry sources 24 hours). Status reporting, not flood prediction.

Parameters:

| Name | In | Required | Type | Description |
| --- | --- | --- | --- | --- |
| `state` | query | no | `string` | Lowercase state code (nsw, vic, qld, sa, wa, tas, nt, act) |
| `floodClass` | query | no | `string` | Filter to gauges at or above this class (>= semantics: minor matches moderate and major too) |
| `lga` | query | no | `string` | ABS LGA code (the same LGA_2022 vocabulary as the declarations API) |
| `source` | query | no | `string` | Polling source (hydstra-nsw, hydstra-vic, hydstra-qld, aquarius-sa, aquarius-tas, aquarius-nt, bom-kiwis) |
| `bbox` | query | no | `string` | Bounding box minLng,minLat,maxLng,maxLat (within Australia) |
| `limit` | query | no | `integer` | Max results per page (1-500, default 100) |
| `cursor` | query | no | `string` | Pagination cursor from meta.nextCursor |

Responses:

| Status | Description |
| --- | --- |
| `200` | Gauge stations with latest readings and flood status |
| `401` | Missing or invalid API key |

Example request:

```bash
curl "https://emergencyapi.com/api/v1/gauges?state=nsw&lga=17750" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

### GET /gauges/{id}

One gauge with a 6-hour recent window

Returns a single gauge station plus its trailing 6 hours of raw readings (enough to see the current trend). Deeper history is the tier-gated /gauges/{id}/readings endpoint.

Parameters:

| Name | In | Required | Type | Description |
| --- | --- | --- | --- | --- |
| `id` | path | yes | `string` | Gauge id from /gauges (e.g. hydstra-nsw-410001) |

Responses:

| Status | Description |
| --- | --- |
| `200` | The gauge and its recent readings |
| `404` | No active gauge with that id |

Example request:

```bash
curl "https://emergencyapi.com/api/v1/gauges/{id}" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

### GET /gauges/{id}/readings

Gauge reading history (paid tier)

Historical water level readings for one gauge. Free tier is blocked (the free surface is current readings on /gauges and the 6-hour window on /gauges/{id}). Starter tier limited to 1 year lookback, Developer and Business to 5 years, Pro and Enterprise unlimited. Retention ladder: raw 30 days, hourly rollups 90 days, daily forever — plus full-resolution raw inside flood-event windows kept forever. interval=auto picks the finest granularity available for the requested window.

Parameters:

| Name | In | Required | Type | Description |
| --- | --- | --- | --- | --- |
| `id` | path | yes | `string` |  |
| `after` | query | no | `string` | Start of range (ISO 8601, inclusive). Tier-limited. |
| `before` | query | no | `string` | End of range (ISO 8601, exclusive). Defaults to now. |
| `interval` | query | no | `string` | raw, hourly, daily, or auto (default) |
| `above` | query | no | `string` | Only readings at/above this published flood classification for the gauge |
| `limit` | query | no | `integer` |  |
| `cursor` | query | no | `string` | Pagination cursor from meta.nextCursor (ISO timestamp keyset) |

Responses:

| Status | Description |
| --- | --- |
| `200` | Readings for the gauge, newest first |
| `403` | Free tier blocked or depth limit exceeded |

Example request:

```bash
curl "https://emergencyapi.com/api/v1/gauges/{id}/readings" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

### GET /gauges/summary

Flood status counts by state or LGA

Counts of gauges at or above minor/moderate/major flood classification, grouped by state or LGA, plus the full list of at-or-above-minor stations (capped at 500). STALE GUARD: only readings within the staleness horizon enter class counts — a days-old reading above minor is counted as stale, never as a current flood signal.

Parameters:

| Name | In | Required | Type | Description |
| --- | --- | --- | --- | --- |
| `groupBy` | query | no | `string` | state (default) or lga (requires the state parameter) |
| `state` | query | no | `string` |  |

Responses:

| Status | Description |
| --- | --- |
| `200` | Flood status summary |

Example request:

```bash
curl "https://emergencyapi.com/api/v1/gauges/summary?state=sa" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

## Schemas

The per-incident `details` object is agency-specific and varies by feed. Full per-feed breakdown: https://emergencyapi.com/guides/incident-details-fields

### IncidentFeature

| Field | Type | Description |
| --- | --- | --- |
| `type` | `"Feature"` |  |
| `id` | `string` |  |
| `geometry` | `object` |  |
| `geometry.type` | `string` | One of: Point, Polygon, MultiPolygon. |
| `geometry.coordinates` | `oneOf` |  |
| `properties` | `object` |  |
| `properties.source` | `object` |  |
| `properties.source.state` | `string` |  |
| `properties.source.agency` | `string` |  |
| `properties.source.feedId` | `string` |  |
| `properties.title` | `string` |  |
| `properties.eventType` | `string` | One of: bushfire, burn_off, fire_ban, structure_fire, vehicle_fire, grass_fire, hazmat, rescue, flood, storm, tree_down, cyclone, earthquake, extreme_heat, vehicle_accident, medical, alarm, other. |
| `properties.eventCategory` | `string` | Groups related event types. See /api/v1/schema for the full mapping. One of: fire, weather, rescue, hazmat, medical, alarm, planned, earth, hazard, other. |
| `properties.featureType` | `string` | Point incident or boundary polygon. Defaults to 'incident'; list endpoints return only incidents unless ?featureType= is supplied. One of: incident, incident_area, warning_area, fire_ban_area. |
| `properties.status` | `string` | One of: active, contained, controlled, safe, completed. |
| `properties.warningLevel` | `string` | One of: advice, watch_and_act, emergency_warning, none. |
| `properties.severity` | `string` | One of: Extreme, Severe, Moderate, Minor, Unknown. |
| `properties.urgency` | `string` | One of: Immediate, Expected, Future, Past, Unknown. |
| `properties.certainty` | `string` | One of: Observed, Likely, Possible, Unlikely, Unknown. |
| `properties.location` | `object` |  |
| `properties.location.address` | `string` |  |
| `properties.location.suburb` | `string` |  |
| `properties.location.state` | `string` |  |
| `properties.location.lga` | `string` |  |
| `properties.location.latitude` | `number` | Centroid latitude (extracted from geometry) |
| `properties.location.longitude` | `number` | Centroid longitude (extracted from geometry) |
| `properties.location.precision` | `string` | Coordinate precision. 'exact' = authoritative point from the source feed. 'postcode' or 'lga' = approximate centroid backfilled for historical archive rows that logged no point. Absent when no coordinates are available (geometry is null). One of: exact, postcode, lga. |
| `properties.details` | `object` | Agency-specific incident metadata, passed through from the source feed. OPTIONAL and varies by feed AND by incident (it is not standardised across agencies, and some feeds carry none). Render whatever keys are present rather than expecting a fixed set. The properties below are the common ones; the full per-feed breakdown (every field, its type and meaning) is documented at https://emergencyapi.com/guides/incident-details-fields |
| `properties.details.description` | `string` | Source detail text; structure varies by feed (NSW RFS alert block, a place name, raw pager text, etc.). |
| `properties.details.resources` | `integer` | Count of resources (crews/appliances/units) assigned or responding. |
| `properties.details.aircraft` | `integer` | Count of aircraft assigned (SA CFS/MFS). |
| `properties.details.decoded_units` | `string[]` | Decoded responding unit names (SA pager feeds). |
| `properties.details.alarm_level_description` | `string` | Alarm/warning level label (SA pager feeds). |
| `properties.details.priority_description` | `string` | Case priority label (SA Ambulance pager). |
| `properties.details.size` | `string` | Incident size label, e.g. Small/Medium/Large (VIC OSOM). |
| `properties.details.cad_id` | `string` | CAD dispatch identifier (e.g. WA DFES 6-digit number) |
| `properties.details.source_id` | `string` | Upstream agency record ID |
| `properties.details.source_url` | `string` | Deep link to the incident on the source agency website |
| `properties.timestamps` | `object` |  |
| `properties.timestamps.reported` | `string` |  |
| `properties.timestamps.updated` | `string` |  |
| `properties.timestamps.fetched` | `string` |  |
| `properties.archive` | `object` | EM-DAT / historical enrichment. Present only on deep-archive snapshot results (meta.source = archive). Each field appears only when populated. |
| `properties.archive.eventStartDate` | `string` |  |
| `properties.archive.eventEndDate` | `string` |  |
| `properties.archive.magnitude` | `number` |  |
| `properties.archive.magnitudeScale` | `string` |  |
| `properties.archive.impactDeaths` | `integer` |  |
| `properties.archive.impactAffected` | `integer` |  |
| `properties.archive.impactEconomic` | `number` |  |
| `properties.archive.glideNumber` | `string` | GLIDE disaster identifier |

### IncidentCollection

| Field | Type | Description |
| --- | --- | --- |
| `type` | `"FeatureCollection"` |  |
| `features` | `IncidentFeature[]` |  |
| `meta` | `object` |  |
| `meta.total_count` | `integer` |  |
| `meta.has_more` | `boolean` |  |
| `meta.next_cursor` | `string` |  |
| `meta.generatedAt` | `string` |  |
| `links` | `object` |  |
| `links.self` | `string` |  |
| `links.next` | `string` |  |
| `attribution` | `string` |  |

### EventFeature

| Field | Type | Description |
| --- | --- | --- |
| `type` | `"Feature"` |  |
| `id` | `string` |  |
| `geometry` | `object` | Boundary polygon (convex hull of cluster) or centroid point |
| `geometry.type` | `string` | One of: Polygon, Point. |
| `geometry.coordinates` | `oneOf` |  |
| `properties` | `object` |  |
| `properties.title` | `string` |  |
| `properties.incidentCount` | `integer` |  |
| `properties.affectedSuburbs` | `string[]` |  |
| `properties.affectedStates` | `string[]` |  |
| `properties.agencies` | `string[]` |  |
| `properties.eventTypes` | `string[]` |  |
| `properties.maxSeverity` | `string` | One of: Extreme, Severe, Moderate, Minor, Unknown. |
| `properties.maxWarningLevel` | `string` | One of: advice, watch_and_act, emergency_warning, none. |
| `properties.estimatedHectares` | `number` |  |
| `properties.summary` | `string` |  |
| `properties.firstDetectedAt` | `string` |  |
| `properties.lastUpdatedAt` | `string` |  |
| `properties.isActive` | `boolean` |  |

### EventCollection

| Field | Type | Description |
| --- | --- | --- |
| `type` | `"FeatureCollection"` |  |
| `features` | `EventFeature[]` |  |
| `meta` | `object` |  |
| `meta.totalEvents` | `integer` |  |
| `meta.generatedAt` | `string` |  |
| `attribution` | `string` |  |

### ProblemDetails

RFC 9457 Problem Details

| Field | Type | Description |
| --- | --- | --- |
| `type` | `string` |  |
| `title` | `string` |  |
| `status` | `integer` |  |
| `detail` | `string` |  |
| `instance` | `string` |  |

### DeclarationRecord

| Field | Type | Description |
| --- | --- | --- |
| `agrn` | `string` |  |
| `title` | `string` |  |
| `instrumentType` | `string` | One of: state_natural_disaster_declaration, drfa_activation_agrn, state_of_disaster_emergency_powers. |
| `jurisdiction` | `string` |  |
| `disasterTypes` | `string[]` |  |
| `startDate` | `string` |  |
| `endDate` | `string` |  |
| `status` | `string` | One of: active, expired, unknown. |
| `source` | `string` | Display name of the highest-precedence reporting source |
| `sources` | `string[]` | Every government source reporting this AGRN+instrument for this LGA. Multiple entries = multiple sources corroborate it. |
| `sourceUrl` | `string` |  |
| `sourcePublishedAt` | `string` |  |

### PostcodeDeclarationRecord

### MatchedLga

| Field | Type | Description |
| --- | --- | --- |
| `lgaCode` | `string` |  |
| `lgaName` | `string` |  |
| `populationShare` | `number` | Share of the postcode's population in this LGA (ABS correspondence). Always the postcode-level share, even when the response is narrowed by suburb (never renormalised). null for point lookups, where population share is not a meaningful concept. |
| `declarationStatus` | `string` | One of: declared, uncertain, activation_only, not_declared. |
| `declarations` | `PostcodeDeclarationRecord[]` |  |

### SuburbNarrowing

Present on postcode responses only when the suburb parameter was supplied.

| Field | Type | Description |
| --- | --- | --- |
| `requested` | `string` | The trimmed caller input (up to 100 characters) |
| `applied` | `boolean` |  |
| `method` | `string` | How suburb-to-LGA membership was derived. spatial_derivation = area-weighted intersection of ABS SAL 2021 and LGA 2022 boundary polygons (the current source; ABS publishes no SAL 2021 to LGA 2022 correspondence); abs_sal_lga_correspondence = a published ABS population-weighted correspondence, if one is adopted later. One of: spatial_derivation, abs_sal_lga_correspondence. |
| `matchedSuburbs` | `object[]` | The ABS SAL suburb(s) the input matched within this postcode. More than one entry means the bare name denotes multiple suburbs (their LGA sets are unioned). |
| `reason` | `string` | Present only when applied is false One of: suburb_not_found_in_postcode, suburb_lgas_outside_postcode, unknown_postcode. |
| `knownSuburbs` | `string[]` | Present only when applied is false and the postcode is known — the postcode's suburb names |

### PostcodeDeclarationResult

| Field | Type | Description |
| --- | --- | --- |
| `postcode` | `string` |  |
| `matchStatus` | `string` | One of: declared, partial, not_declared, uncertain, activation_only, unknown_postcode. |
| `matchStatusReason` | `string` | Present when matchStatus is uncertain or activation_only |
| `matchedLgas` | `MatchedLga[]` |  |
| `narrowing` | `SuburbNarrowing` |  |
| `asAt` | `string` | Date the status was evaluated against; the requested as_at value or today (AEST) when omitted |
| `dataLastUpdated` | `string` |  |
| `stale` | `boolean` |  |
| `disclaimer` | `string` |  |
| `attribution` | `string` |  |

### PointLookupRequest

| Field | Type | Description |
| --- | --- | --- |
| `lat` | `number` |  |
| `lng` | `number` |  |
| `as_at` | `string` | Point-in-time check (YYYY-MM-DD). Defaults to today. |
| `include_expired` | `boolean` | Include expired records in the per-LGA lists. Never changes matchStatus. |
| `instrument_type` | `string` | Trim the returned record lists to one instrument type. Never changes matchStatus. One of: state_natural_disaster_declaration, drfa_activation_agrn, state_of_disaster_emergency_powers. |

### PointDeclarationResult

| Field | Type | Description |
| --- | --- | --- |
| `matchStatus` | `string` | One of: declared, partial, not_declared, uncertain, activation_only, unknown_location. |
| `matchStatusReason` | `string` | Present when matchStatus is uncertain or activation_only |
| `matchedLgas` | `MatchedLga[]` | Normally one area. Two areas only when the point lies exactly on a shared boundary (onBoundary=true); partial is then possible and means the covering areas have different statuses. |
| `onBoundary` | `boolean` | Present (true) only when the point lies on a shared LGA boundary and more than one area is returned. |
| `boundaryEdition` | `string` | ABS boundary edition the point was resolved against. Informative, not an enum — it changes with ASGS edition refreshes. LGA matching is at ABS code level; point-in-polygon cannot be more precise than the code. |
| `asAt` | `string` | Date the status was evaluated against; the requested as_at value or today (AEST) when omitted |
| `dataLastUpdated` | `string` |  |
| `stale` | `boolean` |  |
| `disclaimer` | `string` |  |
| `attribution` | `string` |  |

### DeclarationListItem

### DeclarationList

| Field | Type | Description |
| --- | --- | --- |
| `declarations` | `DeclarationListItem[]` |  |
| `dataLastUpdated` | `string` |  |
| `stale` | `boolean` |  |
| `disclaimer` | `string` |  |
| `links` | `object` |  |
| `links.next` | `string` |  |
| `attribution` | `string` |  |

### DeclarationDetail

| Field | Type | Description |
| --- | --- | --- |
| `agrn` | `string` |  |
| `title` | `string` |  |
| `instrumentType` | `string` |  |
| `jurisdiction` | `string` |  |
| `disasterTypes` | `string[]` |  |
| `startDate` | `string` |  |
| `endDate` | `string` |  |
| `status` | `string` | One of: active, expired, unknown. |
| `source` | `string` |  |
| `sourcePublishedAt` | `string` |  |
| `sourceUrl` | `string` |  |
| `contributingSources` | `object[]` |  |
| `affectedLgas` | `object[]` |  |
| `dataLastUpdated` | `string` |  |
| `stale` | `boolean` |  |
| `disclaimer` | `string` |  |
| `attribution` | `string` |  |

### Gauge

A river gauge station with its latest reading and derived flood status. Readings are metres relative to the gauge's local datum, not sea level.

| Field | Type | Description |
| --- | --- | --- |
| `id` | `string` |  |
| `name` | `string` |  |
| `river` | `string` |  |
| `state` | `string` |  |
| `agency` | `string` |  |
| `source` | `string` |  |
| `awrcStationNo` | `string` |  |
| `coordinates` | `object` |  |
| `coordinates.lat` | `number` |  |
| `coordinates.lng` | `number` |  |
| `lga` | `object` |  |
| `lga.code` | `string` |  |
| `lga.name` | `string` |  |
| `latest` | `object` |  |
| `latest.value` | `number` |  |
| `latest.observedAt` | `string` |  |
| `latest.quality` | `string` |  |
| `readingStatus` | `string` | One of: live, stale. |
| `floodClass` | `string` | Derived at read time from the latest reading vs the published BoM thresholds; never stored as judgement. One of: below_minor, minor, moderate, major, unclassified. |
| `thresholds` | `object` |  |
| `thresholds.minor` | `number` |  |
| `thresholds.moderate` | `number` |  |
| `thresholds.major` | `number` |  |
| `thresholds.unit` | `string` |  |
| `thresholds.source` | `string` |  |
| `thresholds.version` | `string` |  |
| `thresholds.fetchedAt` | `string` |  |
| `datum` | `object` |  |
| `datum.gaugeZeroM` | `number` |  |
| `datum.datum` | `string` |  |

### GaugeReading

A raw reading (observedAt/value/quality) or an aggregated bucket (bucket/min/max/mean/nObs), depending on the interval.

| Field | Type | Description |
| --- | --- | --- |
| `observedAt` | `string` |  |
| `value` | `number` |  |
| `quality` | `string` |  |
| `bucket` | `string` |  |
| `min` | `number` |  |
| `max` | `number` |  |
| `mean` | `number` |  |
| `nObs` | `integer` |  |

### GaugeCollection

| Field | Type | Description |
| --- | --- | --- |
| `gauges` | `Gauge[]` |  |
| `meta` | `object` |  |
| `meta.count` | `integer` |  |
| `meta.hasMore` | `boolean` |  |
| `meta.nextCursor` | `string` |  |
| `meta.generatedAt` | `string` |  |
| `disclaimer` | `string` |  |
| `attribution` | `string` |  |