Metrics
Every metric, its canonical unit, the units it accepts, and the published standard it is graded against.
34 metrics, covering what consumer and prosumer air quality hardware actually reports. 19 are graded against a cited published standard. 15 are deliberately ungraded — no standard exists, and inventing bands would be worse than saying so.
This table is generated from the same catalogue the API enforces, so it cannot
drift from the behaviour. Machine-readable at /v1/meta.
Grading
Severity is anchored to published thresholds, never to the range of values currently on screen. A relative scale would paint the worst reading red on a day when everything is fine — on a public map that is a false alarm, not a cosmetic choice.
Two threshold shapes:
- rising — more is worse. The first step whose
upTothe value does not exceed wins; anything past the last step iscritical. - comfort — two-sided, where both too little and too much are worse. Humidity is the only one.
Particulate
| Key | Unit | Range | Also accepts | Graded against |
|---|---|---|---|---|
| pm1p0 | µg/m³ | 0–1000 | mg/m3 | No PM1 standard — PM2.5 bands used as a proxy |
| pm2p5 | µg/m³ | 0–1000 | mg/m3 | US EPA 24-hour PM2.5 breakpoints |
| pm4p0 | µg/m³ | 0–1000 | mg/m3 | No PM4 standard — PM10 bands used as a proxy |
| pm10p0 | µg/m³ | 0–2000 | mg/m3 | US EPA 24-hour PM10 breakpoints |
| pc0p3 | #/L | 0–50000000 | #/dL, #/cm3, #/0.1L | ungraded — No health standard — raw sensor counts |
| pc0p5 | #/L | 0–50000000 | #/dL, #/cm3, #/0.1L | ungraded — No health standard — raw sensor counts |
| pc1p0 | #/L | 0–50000000 | #/dL, #/cm3, #/0.1L | ungraded — No health standard — raw sensor counts |
| pc2p5 | #/L | 0–50000000 | #/dL, #/cm3, #/0.1L | ungraded — No health standard — raw sensor counts |
| pc5p0 | #/L | 0–50000000 | #/dL, #/cm3, #/0.1L | ungraded — No health standard — raw sensor counts |
| pc10p0 | #/L | 0–50000000 | #/dL, #/cm3, #/0.1L | ungraded — No health standard — raw sensor counts |
The pc* metrics are raw optical counts per litre. No health standard exists
for counts, but they are the rawest thing the sensor knows and discarding them
would throw away the evidence behind the mass estimate.
Gases
| Key | Unit | Range | Also accepts | Graded against |
|---|---|---|---|---|
| co2 | ppm | 0–40000 | — | ASHRAE / common IAQ guidance (sensor range 0-40,000 ppm) |
| eco2 | ppm | 0–60000 | — | Estimated value — not a measurement. CO₂ bands shown for orientation only |
| co | ppm | 0–1000 | ppb, mg/m3, ug/m3 | US EPA AQI 8-hour CO breakpoints |
| no2 | ppb | 0–5000 | ppm, ug/m3 | US EPA AQI 1-hour NO₂ breakpoints |
| no | ppb | 0–5000 | ppm, ug/m3 | ungraded — No health standard — NO is a precursor and is regulated as NO₂ |
| nox | ppb | 0–10000 | ppm, ug/m3 | ungraded — No combined standard — graded via NO₂ where available |
| o3 | ppb | 0–1000 | ppm, ug/m3 | US EPA AQI 8-hour ozone breakpoints |
| so2 | ppb | 0–5000 | ppm, ug/m3 | US EPA AQI 1-hour SO₂ breakpoints |
| nh3 | ppb | 0–100000 | ppm, ug/m3 | ungraded — No ambient health standard — occupational limits only (ACGIH 25 ppm TWA) |
| h2s | ppb | 0–50000 | ppm, ug/m3 | WHO air quality guideline, 24-hour (150 µg/m³ ≈ 107 ppb) |
| hcho | ppb | 0–10000 | ppm, ug/m3, mg/m3 | WHO indoor guideline, 30-minute (100 µg/m³ ≈ 81 ppb) |
| benzene | ppb | 0–10000 | ppm, ug/m3 | EU Directive 2008/50/EC annual limit 5 µg/m³ (~1.6 ppb); WHO states no safe level |
| tvoc_ppb | ppb | 0–60000 | ppm, mg/m3 | ungraded — No single published standard — vendors differ on what TVOC includes |
| radon | Bq/m³ | 0–20000 | pCi/L | WHO Handbook on Indoor Radon (reference level 100 Bq/m³; US EPA action level 148) |
Two things called TVOC
tvoc is an index — a relative scale against the sensor's own baseline,
which is what UniFi and Sensirion report. tvoc_ppb is a concentration,
which is what Awair and SGP30-class parts report. They are not convertible, and
conflating them would attach ppb-scale health thresholds to an index-scale
reading.
eco2 is likewise kept separate from co2: it is estimated from a VOC sensor
rather than measured by an NDIR one. It tracks occupancy but is not
interchangeable.
Indices
| Key | Unit | Range | Also accepts | Graded against |
|---|---|---|---|---|
| aqi | index | 0–500 | — | US EPA AQI categories (sensor range 0-500) |
| voc | idx | 1–500 | — | UniFi spec: VOC Index 1-500 (Sensirion scale) |
| nox_index | idx | 1–500 | — | ungraded — No health standard — index scale only (Sensirion SGP41) |
| tvoc | idx | 0–1000 | — | ungraded — UniFi spec: index scale, no published health mapping |
Environment
| Key | Unit | Range | Also accepts | Graded against |
|---|---|---|---|---|
| temperature | °C | -40–85 | F, K | ungraded — Comfort range only — not a health threshold |
| humidity | % | 0–100 | — | EPA / ASHRAE indoor humidity guidance |
| pressure | hPa | 800–1200 | Pa, kPa, inHg, mbar | ungraded — No health threshold |
| noise | dBA | 0–140 | — | WHO Environmental Noise Guidelines (road traffic, Lden 53 dB) |
| illuminance | lx | 0–200000 | — | ungraded — No health threshold |
| uv_index | idx | 0–20 | — | WHO Global Solar UV Index |
Not air quality, but the same sensors report them and they matter for interpretation — low-cost particulate sensors read high in high humidity, which is the sensor rather than the air.
Units
Gas conversions between mixing ratios (ppb, ppm) and mass concentrations (µg/m³, mg/m³) assume EPA reference conditions:
25 °C, 1 atm — molar volume 24.45 L/mol
At 0 °C the molar volume is 22.41 and the same reading converts about 9% differently. The assumption is stated rather than implied, because a converted number that does not state its reference conditions is not a measurement.
Aliases
Metric names are forgiving on the way in. pm25, PM2.5, pm2_5 and pm2p5
are the same metric; so are temp and temperature, rh and humidity,
ozone and o3. An agent written against another vocabulary lands in the right
column instead of being rejected or creating a parallel metric nobody charts.
The canonical key is always what comes back out.