What You’re Actually Getting When You Request Air Quality Data
The air_quality object in a WeatherAPI forecast or current-conditions response looks deceptively simple: a handful of numeric fields, two index values, done. But the fields bundle together measurement concepts that behave very differently from each other — and if you treat them interchangeably, or assume they share the same reliability characteristics, you’ll quietly build something that misleads users at exactly the moments they care most.
Here’s what the response actually gives you:
- Raw pollutant concentrations:
co(carbon monoxide, μg/m³),no2(nitrogen dioxide, μg/m³),o3(ozone, μg/m³),so2(sulphur dioxide, μg/m³),pm2_5(fine particulate, μg/m³),pm10(coarse particulate, μg/m³) - Derived composite indices:
us-epa-index(1–6 scale) andgb-defra-index(1–10 scale)
Those two categories are not the same kind of data and shouldn’t be handled identically in your application logic.
The Composite Indices: What the Numbers Actually Represent
The US EPA index maps to the familiar AQI color bands — 1 is Good (0–50 AQI), 2 is Moderate (51–100), up through 6 which is Hazardous (301+). The actual EPA AQI is a 0–500 scale; WeatherAPI collapses that into six ordinal buckets. If you need to distinguish between AQI 155 and AQI 180 — both map to “Unhealthy,” but that gap matters for a running app deciding whether to recommend indoor workouts — the us-epa-index value of 4 won’t help you. You’d need to compute AQI yourself from the raw concentration fields.
The DEFRA index runs 1–10 and was developed specifically for UK air quality monitoring. It uses different breakpoints and a different dominant-pollutant methodology than the US EPA system. A 6 on the DEFRA scale sits in the “High” band under thresholds set by the UK Department for Environment, Food and Rural Affairs; a 6 on the EPA scale is Hazardous. They are not the same number on the same scale. We’ve seen developers build UIs that display both values side by side without labeling them — don’t do that.
pm2_5 Is the Field You Should Build Around
For anything health-adjacent — outdoor activity recommendations, HVAC control, construction site safety, agricultural spray timing — pm2_5 is the field that matters most. Fine particulate under 2.5 micrometers penetrates deep into lung tissue and is the primary driver of health effects during air quality events. Ozone matters too, particularly for respiratory conditions, but PM2.5 is what moves fastest near wildfire smoke, heavy traffic, or industrial activity.
The raw μg/m³ value gives you something to act on that index buckets obscure. WHO’s 2021 updated guidelines set the annual mean target at 5 μg/m³ and the 24-hour mean at 15 μg/m³. The US EPA 24-hour NAAQS standard sits at 35 μg/m³. Those are real thresholds you can put directly in code:
if (airQuality.pm2_5 > 35.4) {
// Above EPA 24-hour standard — flag for outdoor activity restriction
}
if (airQuality.pm2_5 > 55.4) {
// Unhealthy for all groups, not just sensitive populations
}That’s more useful than a bucket that lumps together everything from 35 to 150 μg/m³.
Where the Data Comes From — and Why That Matters for Reliability
Air quality data in forecast APIs typically blends two sources: ground-based monitoring networks (EPA’s AQS in the US, AURN in the UK) and atmospheric chemistry model output — primarily CAMS from the Copernicus Atmosphere Monitoring Service for global coverage. For current conditions, proximity to a monitoring station matters a lot. For forecasts, you’re getting model output trained against station data, not a direct measurement of your specific location.
The station coverage problem is worse for air quality than for temperature. The US has roughly 4,000 AQS monitoring sites across 9.8 million km². Rural areas, tribal lands, and mountainous terrain are largely unmonitored. In those places, what the API returns is model interpolation, and the uncertainty is real.
This is most consequential during wildfire events. Smoke plumes can push PM2.5 from background levels around 5–8 μg/m³ to over 200 μg/m³ within a couple of hours, and that change can be intensely localized — a monitoring station 20 km away may not be in the plume at all. Model forecasts typically lag behind fast-moving smoke because fire emission inventories take time to be updated and assimilated into the model cycle. This is the single biggest failure mode we run into: users in wildfire-affected regions getting API readings that say “Good” while their sky is visibly orange.
There’s no clean fix for this. PurpleAir’s dense consumer-sensor network helps fill geographic gaps but introduces its own accuracy problems — low-cost optical sensors read high in humid conditions, which is why EPA developed correction factors in the 2021 AQS-PM2.5 regression model. The honest framing is that API-sourced air quality in areas without nearby regulatory monitoring should be treated as a rough directional signal, not a precise reading.
Ozone and Time of Day: The Temporal Trap
Ozone (o3) is photochemically produced — sunlight drives the reaction between NOx and volatile organic compounds, which means concentrations follow a predictable daily cycle: low in early morning, peaking in the early-to-mid afternoon, dropping after sunset. Pull a single daily air quality reading at 7am and the ozone figure looks fine. Pull it at 2pm on a hot sunny day and it can be 30–40% higher.
For ozone-sensitive use cases — outdoor sports scheduling, anything involving users with asthma — hourly resolution is worth the extra API calls. The forecast endpoint returns hourly air quality when you request it.
CO in the Response Is Not What You Think It Is
The co value is ambient outdoor carbon monoxide in μg/m³. Typical urban background readings run 200–1,000 μg/m³; the EPA 8-hour standard is 10,000 μg/m³ (roughly 9 ppm). If a user sees 500 in your app and reads it as an indoor CO risk, that’s a UI failure on your end. The field measures outdoor CO from vehicle exhaust and industrial combustion — not the kind of reading that triggers a household CO alarm. Label it accordingly.
One Thing Worth Knowing Before You Build
The us-epa-index and gb-defra-index fields are most useful for simple color-coded indicators where you need an immediately human-readable signal and don’t want to implement your own pollutant-to-AQI conversion. For anything that needs precision — health-critical thresholds, automated alerts, actuating physical systems — build against the raw concentration fields and apply breakpoints directly from the EPA or WHO published tables. The bucket indices trade resolution for convenience; whether that trade-off makes sense depends entirely on your use case.
If you’re operating in a region with sparse monitoring where wildfires are a seasonal reality, surface a caveat in your UI during conditions where model-based estimates are most likely to lag. That’s not a hedge — it’s the accurate thing to do.