# CrashMap: full guide

> CrashMap (https://crashmap.nz) is a free, interactive map of New Zealand roads ranked by expected death-or-serious-injury (DSI) crashes per km per year, predicted by machine-learning models from the NZ Transport Agency Waka Kotahi Crash Analysis System (CAS). This file describes the whole tool for language models and other automated readers: what it shows, how it is calculated, every control and URL parameter, the API, and the limits.

Short version: https://crashmap.nz/llms.txt

## About

- **Name**: CrashMap
- **URL**: https://crashmap.nz (web app), https://api.crashmap.nz (read-only API)
- **Cost**: free, no account
- **Language**: New Zealand English
- **Coverage**: New Zealand; crashes from 2022, 2023, 2024 and 2025
- **Developed and published by**: Tasman Tech (https://tasmantech.co.nz), an Auckland web development company
- **Status**: a research tool built from the experiments in a master's project on predicting crash severity in New Zealand. It is not an official NZ Transport Agency product and is not advice for any individual journey.
- **Requirements**: a browser with JavaScript and WebGL (the map is Google Maps with deck.gl layers)

## What the map answers

Which New Zealand roads have the most expected fatal and serious-injury crashes per km, overall or under particular conditions (for example heavy rain at night), and how well the underlying models tell DSI crashes from minor ones.

## How road risk is calculated

The models predict the probability that a crash is fatal or serious *given that it happened*. A road's expected DSI is the sum of those probabilities over the crashes recorded on it: frequency from the crash record, severity from the model.

1. Roads come from the Geofabrik New Zealand OpenStreetMap extract. Ways are merged by road name and cut into lengths of at most 1 km. There are 39,330 road lengths, about 26,500 km in total.
2. Each crash is snapped to the nearest road length within 30 m, preferring one whose name matches the CAS road name. About 99 per cent of crashes snap; about 0.7 per cent are not within 30 m of a mapped road and are left out.
3. Each road length's expected DSI is divided by its length (at least 0.5 km is used, so very short stretches are not inflated) and by the number of years selected.
4. Road lengths are ranked by expected DSI per km per year and banded by share of ranked road length:

| Band | Share of ranked road length |
| --- | --- |
| High | top 2 per cent |
| Medium-high | 2–5 per cent |
| Medium | 5–15 per cent |
| Low-medium | 15–40 per cent |
| Low | the rest |

Bands are relative, so they move with the filters. The legend shows the value each band starts at. Road lengths need at least a minimum number of crashes (default 2) to be ranked.

No model is refitted in the tool. It reads the probabilities each experiment saved, and each stored set must reproduce the metrics the experiment published (PR-AUC, ROC-AUC, precision and recall within 5e-5) to be included.

## The data

| Year | Crashes | DSI crashes | DSI share |
| --- | --- | --- | --- |
| 2022 | 31,415 | 2,477 | 7.9% |
| 2023 | 31,639 | 2,420 | 7.6% |
| 2024 | 29,470 | 2,390 | 8.1% |
| 2025 | 28,987 | 2,322 | 8.0% |

About 121,500 crashes in all. DSI means a crash with at least one death or serious injury.

### Model configurations (86)

Five model families: XGBoost, LightGBM, CatBoost, random forest and logistic regression, combined with different class-balancing approaches (none, class weighting, SMOTENC resampling, scaled class-weight ratios) and tuning set-ups.

| Set | Configurations | What it is | Years scored |
| --- | --- | --- | --- |
| Set 0: baseline | 15 | Baseline settings | 2025 |
| Set 1: refined search | 15 | Refined hyperparameter search | 2025 |
| Set 2: PR-AUC tuning | 15 | Tuned for PR-AUC | 2025 |
| Set 3: calibrated, cost rule | 15 | Calibrated probabilities, cost-based threshold | 2025 |
| Optuna control | 4 | Optuna search as a control | 2025 |
| Sensitivity: no object-struck | 4 | Without the object-struck variables | 2025 |
| Rolling-origin backtest | 6 | Each year scored by a model trained only on earlier years | 2022–2025 |
| Backtest: class-weight ratios | 6 | Backtest with the class-weight ratio raised to 0.25, 0.75 and 1 | 2022–2025 |
| Backtest: engineered features | 6 | Backtest with extra engineered features | 2022–2025 |

The **leading model** is the backtest configuration with the highest mean validation PR-AUC over 2022–2024: XGBoost without class balancing (0.3060). It is first among several statistically indistinguishable ensembles, and the map uses it by default.

## The two tabs

### High-risk roads (default)

1. **Road conditions**: weather, wind and frost, light, road surface, area, speed limit, terrain, road type and road feature. Only crashes recorded under the chosen conditions count, so "Heavy rain + Dark" ranks roads by their wet-night risk. Nothing selected in a group means all of it.
2. **Model configuration**:
   - *One backtest model* (default: the leading model; any of the 18 backtest-family configurations can be chosen): years 2022–2025, each scored by a model that never saw that year.
   - *Five leading ensembles, averaged*: the five are statistically indistinguishable, so they are averaged rather than one being picked. Each road length also records how many of the five put it in the top 5 per cent.
   - *Any configuration, 2025 only*: any of the 86 configurations, on 2025 alone.
3. **Highest-risk roads**: road lengths in the top 5 per cent, grouped by road and district. Sort by *Most DSI a year* (favours long roads) or *Highest per km* (favours short, intense stretches). Selecting a road zooms the map to it.

### Model diagnostics

How the selected configuration classified each crash in a scored year.

- **Outcome view**: red = DSI missed, purple = DSI found, yellow = false alarm. Shown as coloured roads (default) or one dot per crash. A road is red if any DSI crash on it was missed, purple if all its DSI crashes were found, yellow if it has only false alarms.
- **Probability view**: the predicted DSI probability of each crash.
- **Heatmap view**: density of the crashes the model flags as DSI.
- **Road metrics view**: roads coloured by flagged crashes per km, missed DSI, mean risk, or observed minus expected DSI (calibrated models only).
- **Threshold**: the model's stored threshold, the F1-optimal threshold, 0.5, a custom value, or one derived from the cost weighting.
- **Cost weighting**: a missed DSI crash costs *n* × a false alarm. In "From cost weighting" mode the threshold is 1 / (1 + *n*), which is only meaningful for calibrated sets (set 3, Optuna, backtest).
- **Metrics**: confusion counts, recall, precision read through lift (precision ÷ base rate, because the DSI share differs between years), PR-AUC, ROC-AUC and cost.

Selecting a crash opens its details and how every configuration scored it.

## URL parameters

The whole selection is kept in the URL query string, so any view can be bookmarked or shared. Parameters left out take their default. Invalid values are ignored.

| Parameter | Values | Default | Meaning |
| --- | --- | --- | --- |
| `tab` | `risk`, `diagnostics` | `risk` | Sidebar tab |
| `source` | `backtest`, `ensemble`, `any` | `backtest` | Where road risk comes from (one backtest model, five leading ensembles averaged, any configuration on 2025) |
| `btConfig` | a backtest config ID, e.g. `backtest/lightgbm-weighted` | the leading model | Backtest model for `source=backtest` |
| `riskYears` | comma-separated subset of `2022,2023,2024,2025` | all four | Years counted in the risk ranking |
| `riskMin` | number | `2` | Minimum matching crashes for a road length to be ranked |
| `riskSort` | `total`, `peak` | `total` | Highest-risk list order: most DSI a year, or highest per km |
| `setKey` | `set0`, `set1`, `set2`, `set3`, `optuna`, `sensitivity`, `backtest`, `backtest_cw`, `backtest_fe` | `set3` | Experiment set (diagnostics, and `source=any`) |
| `model` | `xgboost`, `lightgbm`, `catboost`, `random_forest`, `logistic_regression` | `lightgbm` | Model family |
| `balancing` | `none`, `weighted`, `smote` (sets 0–3), `pow025`, `pow075`, `pow100` (`backtest_cw`) | `weighted` | Class-balancing arm: no balancing, class weighting, SMOTENC resampling, or class-weight ratio raised to 0.25, 0.75 or 1 |
| `year` | a scored year of the configuration | `2025` | Diagnostics year |
| `mode` | `stored`, `cost`, `f1`, `half`, `custom` | `stored` | Threshold rule |
| `costRatio` | number | `10` | Cost of a missed DSI crash relative to a false alarm |
| `custom` | number between 0 and 1 | `0.2` | Threshold for `mode=custom` |
| `view` | `outcome`, `probability`, `heatmap`, `roads` | `outcome` | Diagnostics map view |
| `display` | `roads`, `dots` | `roads` | Draw outcome/probability as roads or crash dots |
| `roadMetric` | `flagged`, `missed`, `risk`, `excess` | `flagged` | Metric for `view=roads` |
| `minRoadCrashes` | number | `3` | Road-metrics view: hide road lengths with fewer crashes than this |
| `showTN` | `1`, `0` | `0` | Also show correctly cleared minor crashes |
| `c.<condition>` | levels joined by `\|` | all | Road-condition filter, see below |

Road-condition filters (`c.<key>=Level|Level`, URL-encoded):

| Key | Label | Levels |
| --- | --- | --- |
| `weather` | Weather | Fine, Light rain, Heavy rain, Mist or fog, Snow or hail, Unknown |
| `windFrost` | Wind and frost | Strong wind, Frost, Neither |
| `light` | Light | Bright sun, Overcast, Twilight, Dark, Unknown |
| `surface` | Road surface | Sealed, Unsealed, Unknown |
| `area` | Area | Urban, Open road |
| `speed` | Speed limit | 50 km/h or less, 60–80 km/h, 90 km/h or more, Unknown |
| `terrain` | Terrain | Flat, Hill, Unknown |
| `highway` | Road type | State highway, Local road, Unknown |
| `feature` | Road feature | None, Bridge, Motorway ramp, Speed hump, Over- or underpass, Rail crossing, Tunnel, Other |

Examples:

- https://crashmap.nz/?source=ensemble — five leading ensembles averaged
- https://crashmap.nz/?c.weather=Heavy+rain&c.light=Dark — wet-night risk
- https://crashmap.nz/?c.area=Open+road&c.highway=State+highway&riskSort=peak — the most intense open-road state highway stretches
- https://crashmap.nz/?c.surface=Unsealed — unsealed-road risk
- https://crashmap.nz/?riskYears=2024,2025 — the two most recent years only
- https://crashmap.nz/?tab=diagnostics&setKey=backtest&model=xgboost&balancing=none&year=2025 — how the leading model classified 2025 crashes
- https://crashmap.nz/?tab=diagnostics&setKey=set3&mode=cost&costRatio=20 — set 3 with a threshold where a missed DSI crash costs 20 false alarms

## API

Base URL: https://api.crashmap.nz. Read-only: GET only (other methods return 405), no authentication, no cookies, rate-limited to 600 requests a minute per visitor. Data responses are cached for a day.

| Endpoint | Returns |
| --- | --- |
| `GET /health` | `{ ok, configs, years }` |
| `GET /configs` | `{ dataVersion, years, configs, conditions }`: every configuration with its set, model, balancing, calibration, threshold rule, mean validation PR-AUC, whether it is the leading model, and per-year threshold, F1 threshold, PR-AUC and ROC-AUC; plus the road-condition filters and their levels |
| `GET /crashes?year=2025` | Crash positions (latitude, longitude), DSI label and road-condition codes for one scored year, in columnar form and in prediction order |
| `GET /crashes/{objectId}` | One crash (CAS object ID): its location, road, region, district, conditions, vehicles involved, fatal and serious counts, and how every configuration scored it |
| `GET /predictions?config={configId}&year=2025` | Predicted DSI probabilities for one configuration and year as a raw little-endian float64 array, in the same order as `/crashes?year=` |
| `GET /roads` | Road segments (name, district, length, path) and the segment each crash is snapped to; large |

Configuration IDs look like `backtest/xgboost-unbalanced`, `backtest_cw/lightgbm-weighted-pow075`, `set3/lightgbm-weighted` or `set3/lightgbm` (SMOTENC); `/configs` lists them all.

## Limits

- **Risk per km, not per vehicle.** There are no traffic volumes, so busy roads rank high partly because they are busy.
- **Recorded crashes only.** The ranking depends on crashes being reported to police and recorded in CAS. Recording of minor and non-injury crashes has fallen since 2019, which changes the mix the models see.
- **Severity given a crash.** The models estimate how likely a crash is to be DSI once it has happened, not how likely a crash is to happen.
- **Unsnapped crashes.** About 0.7 per cent of crashes are not within 30 m of a mapped road and are left out of the road ranking.
- **Model differences.** The five leading ensembles are statistically indistinguishable across 2022–2024; differences between them are mostly noise.
- **Relative bands.** Bands are shares of the ranked road length under the current filters, not fixed thresholds.

## Sources and licences

- Crash records: Crash Analysis System (CAS), NZ Transport Agency Waka Kotahi, https://opendata-nzta.opendata.arcgis.com/, licensed under CC BY 4.0.
- Roads: © OpenStreetMap contributors, via the Geofabrik New Zealand extract, Open Database Licence (https://www.openstreetmap.org/copyright).
- CrashMap predictions, rankings and API: © Tasman Tech Limited, not openly licensed. The map is free to use; see https://crashmap.nz/terms.
- Base map: Google Maps.

## How to cite a view

Link to the exact view (the URL carries the whole selection), name the model configuration and years, and note that ranks are expected DSI crashes per km per year from recorded crashes, without traffic volumes.