NZTA Crash Data NZ

Overview

Read-only CLI over the NZTA/Waka Kotahi Crash Analysis System (CAS) public open-data layer. It uses the no-login ArcGIS FeatureServer for bounded, paginated queries and data.govt.nz CKAN for source discovery.

Use it for questions about New Zealand road deaths, fatal crashes, serious or minor injury crashes, regional/TLA crash records, yearly road tolls, and public crash indicator fields such as weather, light, road surface, vehicle types, roadside objects, and roadworks.

Do not use it for live state-highway incidents, closures, or roadworks; use nz-road-closures for current operational road status. The public CAS layer does not expose exact crash dates or detailed driver contributing-factor codes such as alcohol/drugs, speed as a cause, or fatigue.

Commands

Run commands from this skill directory with python3 scripts/cli.py .... Every data command accepts --json.

Command	Purpose	Key flags
datasets	Check ArcGIS FeatureServer and CKAN mirror reachability	--json
crashes	Return bounded crash records with pagination	--region, --from, --to, --severity, --limit, --json
road-toll	Sum fatalities and fatal crashes for a calendar year	--year, --json
factors	Aggregate public CAS indicator fields	--region, --from, --to, --top, --json

crashes accepts --severity fatal|serious|minor|non-injury. --region matches either region or tlaName as a substring, so Auckland, Wellington, and Selwyn are valid examples.

The public layer exposes crashYear and crashFinancialYear, not exact crash dates. --from and --to are accepted as YYYY-MM-DD, but the CLI applies them as calendar-year bounds and includes a date_precision note in outputs. If no date window is supplied, crashes and factors default to a bounded recent two-calendar-year window.

Examples

# Confirm source endpoints and mirror resources
python3 scripts/cli.py datasets --json

# Fatal crash records in Auckland for 2025
python3 scripts/cli.py crashes --region Auckland --from 2025-01-01 --to 2025-12-31 --severity fatal --limit 10

# Machine-readable current-year road toll
python3 scripts/cli.py road-toll --year 2026 --json

# Public indicator aggregation for Wellington over a bounded window
python3 scripts/cli.py factors --region Wellington --from 2024-01-01 --to 2025-12-31 --json

Notes

• CAS is updated monthly. Fatal crashes are usually available within about 1 working day; serious and minor injury crashes may lag by about 4 weeks, so recent DSI/minor counts can be incomplete.
• The ArcGIS layer page size is capped by the service; crashes uses resultOffset/resultRecordCount and enforces a local --limit cap to avoid unbounded full-history downloads.
• --source auto uses ArcGIS first and falls back to a capped CSV mirror scan if ArcGIS is unavailable. CSV fallback is intentionally capped by --scan-cap and may be partial for broad/current queries.
• Endpoint details, field caveats, and pagination notes are in references/api-notes.md.
• The reusable CLI and smoke test live in scripts/.

Resources

• API/source notes: references/api-notes.md
• CLI: scripts/cli.py
• Smoke test: scripts/smoke_test.py