airq

# 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: ```bash airq --version ``` If not installed, detect the user's platform: ### macOS (Homebrew) ```bash brew tap fortunto2/tap && brew install airq ``` ### Linux (prebuilt binary) ```bash curl -LO https://github.com/fortunto2/airq/releases/latest/download/airq-linux-x86_64.tar.gz tar xzf airq-linux-x86_64.tar.gz sudo mv airq /usr/local/bin/ ``` ### Any platform (Rust/cargo) ```bash cargo install airq ``` ## Configuration (recommended) If the user mostly checks the same city, set up a config — then just type `airq` without flags: ```bash airq init --city <city-name> ``` This creates `~/.config/airq/config.toml`. Can also add a favorites list to check multiple cities at once: ```toml default_city = "berlin" cities = ["berlin", "tokyo", "istanbul", "new york"] ``` ```bash airq # checks berlin (default) airq --all # checks all 4 cities, ranked by pollution ``` ## Commands ### Current air quality ```bash airq # uses default city from config airq --city tokyo # specific city airq --lat 55.75 --lon 37.62 # by coordinates ``` Output shows PM2.5, PM10, CO, NO2, O3, SO2, UV index with color-coded AQI. ### History (sparkline trend) ```bash airq history --city berlin --days 7 ``` Shows daily AQI with sparkline bars for the past N days. ### Rank cities by pollution ```bash airq top --country germany # top 5 cities airq top --country turkey --count 10 # top 10 ``` Any country in the world — 10,000+ cities built-in. Use `--list` to see all countries. ### Compare data sources ```bash airq compare --city berlin # model vs area sensors airq compare --city berlin --sensor-id 72203 # model vs specific sensor ``` Side-by-side table showing Open-Meteo model vs Sensor.Community readings. ### Find nearby sensors ```bash airq nearby --city paris --radius 10 ``` Lists Sensor.Community sensor IDs within the given radius (km). ### Single data source ```bash airq --city berlin --provider open-meteo # model only airq --city berlin --provider sensor-community --sensor-id 72203 # sensor only ``` ### Pollution front detection ```bash airq front --city hamburg --radius 150 --days 3 airq front --city gazipasa --radius 150 --days 3 ``` Detects pollution fronts moving between cities using: - 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) ```bash airq blame --city hamburg --radius 20 --days 7 ``` Identifies which factories, power plants, or highways contribute to pollution using CPF (Conditional Probability Function). Sources auto-discovered from OpenStreetMap via Overpass API. Custom sources can be added in config `[[sources]]`. ### HTML/PDF report with map, heatmap, and source attribution ```bash airq report --city hamburg --radius 150 --pdf airq report --city delhi --radius 200 --days 3 --pdf ``` Generates self-contained HTML report with: - 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 - `--pdf` exports via Chrome headless or wkhtmltopdf Data cached in `~/.cache/airq/` (sensor CSV + Overpass responses). ### JSON output All commands support `--json` for scripting and piping: ```bash airq --city tokyo --json airq history --city berlin --days 7 --json airq top --country usa --json ``` ## AQI scale | AQI | Status | Action | |---------|--------------------------------|-------------------------------| | 0-50 | Good | No restrictions | | 51-100 | Moderate | Sensitive people limit outdoor | | 101-150 | Unhealthy for Sensitive Groups | Reduce prolonged outdoor | | 151-200 | Unhealthy | Everyone limit outdoor | | 201-300 | Very Unhealthy | Avoid outdoor activity | | 301-500 | Hazardous | Stay indoors | ## 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.