airq — CLI Air Quality Checker

Check air quality for any city from the terminal. Merges model data (Open-Meteo) with real citizen science sensors (Sensor.Community). No API keys needed.

Installation

First check if airq is already installed:

CODEBLOCK0

If not installed, detect the user's platform:

macOS (Homebrew)

Linux (prebuilt binary)

Any platform (Rust/cargo)

Configuration (recommended)

If the user mostly checks the same city, set up a config — then just type airq without flags:

CODEBLOCK4

This creates ~/.config/airq/config.toml. Can also add a favorites list to check multiple cities at once:

CODEBLOCK5

CODEBLOCK6

Commands

Current air quality

Output shows PM2.5, PM10, CO, NO2, O3, SO2, UV index with color-coded AQI.

History (sparkline trend)

airq history --city berlin --days 7

Rank cities by pollution

airq top --country germany            # top 5 cities
airq top --country turkey --count 10  # top 10

Compare data sources

airq compare --city berlin                     # model vs area sensors
airq compare --city berlin --sensor-id 72203   # model vs specific sensor

Find nearby sensors

airq nearby --city paris --radius 10

Single data source

Pollution front detection

airq front --city hamburg --radius 150 --days 3
airq front --city gazipasa --radius 150 --days 3

• - Z-score spike detection on hourly PM2.5 differences
• Cross-correlation with time-lag between city/sensor pairs
• Haversine distance + bearing for speed and direction
• Dual-source: Open-Meteo model + Sensor.Community archive data
• Sensor clustering (~5km zones) with geo-named labels

Shows nearby cities, wind, spikes, fronts with speed/direction, and ETA warnings.

Pollution source attribution (blame)

airq blame --city hamburg --radius 20 --days 7

HTML/PDF report with map, heatmap, and source attribution

airq report --city hamburg --radius 150 --pdf
airq report --city delhi --radius 200 --days 3 --pdf

• - Leaflet.js map with CartoDB tiles
• PM2.5 heatmap overlay (leaflet.heat)
• Individual sensors colored by air quality level
• Front arrows (green=strong, yellow=medium, orange=weak correlation)
• Pollution source markers on map (⚡ power plants, 🏭 factories, 🛣 highways)
• Source Attribution (CPF) table
• Key Insights, Spikes table, Fronts table, Methodology, AQI reference
• INLINECODE5 exports via Chrome headless or wkhtmltopdf

Data cached in ~/.cache/airq/ (sensor CSV + Overpass responses).

JSON output

AQI scale

How it works

By default airq fetches both sources concurrently and averages PM2.5/PM10:

• - Open-Meteo — atmospheric model (~11km grid, global coverage)
• Sensor.Community — median of real sensors within 5km (filters outliers)

If no sensors are nearby, falls back to model only.