# Rank and color alerts by significance

> Why to color and sort alerts by VTEC significance rather than CAP severity, and how the API's own ranking orders them.

Developers · Concept · https://wxalerts.org/docs/developers/concepts/ranking-alerts/

Each alert carries a CAP `severity` and a VTEC `significance`. Color and rank by
significance: it is the axis the NWS asks people to read. CAP severity is too
coarse to sort on. A Tornado Warning, a Flood Warning and a Winter Storm Watch
can all be `Severe`, plenty of warnings are only `Moderate`, and a Special
Weather Statement is `Moderate` too, which is not a watch.

| `significance` | Meaning |
| --- | --- |
| `W` | Warning: occurring or imminent |
| `A` | Watch: conditions favourable |
| `Y` | Advisory: less serious |
| `S` | Statement |

`significance` and `phenomena` are `null` on products with no VTEC, chiefly
Special Weather Statements and Marine Weather Statements. Fall back to CAP
`severity` for those (`Extreme` reads as a warning, `Severe` as a watch,
`Moderate` as an advisory), which is what the API's own ranking does.

## The ranking

Routes that return alerts "most serious first" sort by significance, then by
hazard (tornado and tsunami, then storm surge, then flash flood, severe
thunderstorm and hurricane, down through winter, fire and flood to marine and
beach hazards), then by CAP `urgency`, then newest. A Flood Warning outranks a
Tornado Watch on purpose: a warning is something happening.

The fields involved are described on the [alerts reference](/docs/api/alerts/),
for example under `GET /alerts/highest-severity`.