A modular FastAPI backend designed to retrieve and standardize air quality data across the J&K & Ladakh region for the BreatheOSS clients. The system aggregates data from multiple providers: OpenMeteo for satellite-based estimates and AirGradient for high-precision ground sensors. It currently calculates AQI based on both Indian (CPCB) and US EPA standards.
The full API documentation (every endpoint, field and quirk, with examples) lives at docs.breatheoss.app. An interactive reference generated from the code is at api.breatheoss.app/docs.
[1] The system accepts a dictionary of raw pollutant values. Before any math occurs, the system sanitizes the input keys using a robust mapping strategy.
-
It handles variations in naming conventions (e.g., mapping "pm2.5", "pm25", or "pm2_5" all to the internal standard pm2_5).
-
This ensures that no data is dropped due to typo-sensitivity or API inconsistencies.
[2] The system calculates AQI using two major standards: Indian (CPCB) and US EPA. Each has specific unit requirements:
-
Indian AQI: PM2.5, PM10, NO2, SO2 are maintained in µg/m³. Carbon Monoxide (CO) and Methane (CH4) are divided by 1000 to convert from µg/m³ to mg/m³.
-
US EPA AQI: Gases (NO2, SO2, CO) are converted from µg/m³ to parts-per-billion (ppb) or parts-per-million (ppm) based on molar volume at 25°C.
-
Methane (CH4) is tracked but currently not included in AQI calculations for either standard.
[3] Once units are standardized, the system calculates an individual Sub-Index for each pollutant using Linear Interpolation.
-
The system scans the
AQI_BREAKPOINTS(Indian) orUS_BREAKPOINTSconfiguration to find the specific range [Clo,Chi] that the current concentration falls into. -
The system applies the standard AQI formula:
$$I = \left[ \frac{I_{hi} - I_{lo}}{C_{hi} - C_{lo}} \times (C - C_{lo}) \right] + I_{lo}$$
Where:
- I: The calculated AQI sub-index.
- C: The current pollutant concentration.
- Clo/Chi: The concentration breakpoints (lower and upper bounds).
- Ilo/Ihi: The corresponding AQI index breakpoints.
The code includes failsafes: if a value exceeds the maximum defined breakpoint, it is capped at 500; if it is below the minimum, it defaults to 0.
[4] The final Air Quality Index is not an average of the pollutants.
- The system identifies the maximum value among all calculated sub-indices.
- The pollutant responsible for this highest value is flagged as the
main_pollutant. - Both the Indian
aqiand theus_aqiare calculated and returned in the final payload.
[5] Averaging Windows: Because official regulations (like the Indian CPCB and US EPA) define AQI using rolling averages rather than instantaneous spikes, the API processes both:
- Live/Instantaneous AQI: Computed directly from current sensor values for real-time spike tracking.
- 24-Hour Average AQI: Computed by first aggregating historical raw concentrations over the past 24 hours, and then running those smoothed values back through the AQI formula.
api/
├── main.py # Entry point
├── Procfile
├── requirements.txt
├── .env
├── breathe.db # Local SQLite database (auto-generated)
└── app/
├── __init__.py
├── api/ # Routes & endpoints
│ ├── __init__.py
│ └── routes.py
├── core/ # Config, database, cache, conversions
│ ├── __init__.py
│ ├── calibration.py
│ ├── config.py
│ ├── database.py
│ ├── conversions.py
│ └── redis_client.py
├── data/ # Static JSON data files
│ ├── __init__.py
│ ├── zones.json
│ ├── nodes.json # AirGradient node configurations
│ ├── sensor_info.json # Hardware sensor metadata
│ ├── aqi_breakpoints.json
│ └── festivals.json # Festival dates for spike protection
└── services/ # Data fetching & processing
├── __init__.py
├── fetchers.py
├── seasonal.py
└── weather.py
main.pyInitializes the FastAPI application and starts a background scheduler. This scheduler runs every 15 minutes to fetch fresh data for all zones, ensuring the app serves cached data instantly without hitting API rate limits during user requests. It also opens the Redis connection pool, and enables Sentry error reporting whenSENTRY_DSNis set.app/api/routes.pyGenerates all/aqi/<zone_id>endpoints dynamically based onzones.json.app/core/database.pyHandles data persistence using PostgreSQL (production) or SQLite (local development). Stores sensor readings, temperature, and humidity for historical graph plotting. Also handles Continuous Aggregations (15-minute rollups) viarefresh_15m_rollupsto serve historical queries with high performance. Also stores per-node offsets (node_offsets), recomputed daily./historical-datauses them to correct multi-sensor zones, so the series doesn't jump when a sensor joins or drops out.app/core/calibration.pyPuts every AirGradient sensor on the same PM2.5 correction, the US EPA 2021 formula with its 2022 extension for smoke. Each sensor can be set to a different correction on AirGradient's side, so it is decided per sensor and per day (IST). For the calm readings, under 200 µg/m³ raw, AirGradient's value is divided by the EPA formula worked out from their own raw PM2.5 and raw humidity. If the median of that is within 0.1 of 1, AirGradient was applying EPA and its values are kept for the whole day, spikes included. If it's 0.15 or more away, the EPA value is served for the whole day. In between, or with fewer than 6 calm readings, each reading is checked on its own. In AirGradient's own export the median is exactly 1.00 every day on EPA sensors, and 1.19 to 2.17 on sensors with the batch correction. Live readings use the sensor's last 24 hours, stored readings their own day, and AirGradient's original value is kept inpm2_5_ag.app/core/config.pyLoads environment variables and configuration fromzones.json,nodes.json,sensor_info.json,aqi_breakpoints.json, andfestivals.json.app/core/conversions.pyHandles the mathematics of AQI calculation, unit conversions (e.g., CO from µg/m³ to mg/m³), and Indian CPCB sub-index mapping along with US EPA sub-index mapping.app/core/redis_client.pyManages the Redis connection pool used to cache the/seasonal,/weather-history, and/historical-dataresponses, and provides the Redis health check.app/services/fetchers.pyContains sophisticated data fetching logic:fetch_openmeteo_live: Queries satellite-based pollutant data.fetch_multi_node_airgradient: Averages data from multiple AirGradient nodes (e.g., Jammu and Srinagar), with built-in spike detection, grace periods for erratic nodes, and stale data protection.get_zone_data: Implements a multi-layered caching strategy. It prioritize ground sensors but automatically falls back to satellite data if physical sensors are offline or reporting unrealistic spikes.
app/services/seasonal.pyBuilds per-zone monthly climatology (average PM2.5, PM10, rainfall, and temperature per calendar month) by backfilling ~4 years of Open-Meteo reanalysis data. Refreshed automatically every 30 days by the background scheduler. Powers the/seasonal/<zone_id>endpoint so clients can show how pollution typically behaves across winter, monsoon, and summer.app/services/weather.pyFetches the live weather condition per zone and classifies it (thunderstorm,rain,snow,fog,smog,clear,cloudy). Fog with high PM2.5 is reported as smog. Generates a season-aware informational text included in the/aqi/<zone_id>payload underweather. Also serves condition-tagged historical buckets for the/weather-historyendpoint so clients can filter AQI history by weather.app/data/zones.jsonContains zone definitions including names, coordinates, andzone_type(hills,urban,industrial).zone_typeis returned to clients aszone_applied, but it doesn't currently change the AQI calculation.app/data/nodes.jsonMaps specific zones to their physical sensor configurations (location_id) and dynamic API token environment variables (token_env_var).app/data/sensor_info.jsonStores hardware-specific metadata for ground sensors (model, coordinates, installation dates).app/data/aqi_breakpoints.jsonOfficial Indian AQI breakpoint tables.app/data/festivals.jsonDiwali dates for each year. On these days the 1-hour spike checks are skipped, and the PM ceilings are raised to the sensor's hardware limit, so that real firecracker spikes aren't filtered out.
- python ≥ 3.10
- fastapi
- httpx
- python-dotenv
- uvicorn
- psycopg2-binary (for Postgres support)
- redis
- sentry-sdk
- A running Redis server
AIRGRADIENT_TOKEN=yourkeyhere
JAMMU_AIRGRADIENT_TOKEN=yourkeyhere
DATABASE_URL=postgres://... (optional, defaults to local sqlite)
UPSTASH_REDIS_URL=redis://... (optional, defaults to redis://localhost:6379)
SENTRY_DSN=... (optional, enables Sentry error reporting)
From the api directory:
uvicorn main:app --reload
Redis must be reachable. Without it, /seasonal, /weather-history, and /historical-data return errors.
The short list is below. For response fields, time range syntax, errors and examples, see docs.breatheoss.app.
-
Zone Data: Access data for a specific zone using its dynamic ID (e.g.,
srinagar,jammu_city,leh):GET /aqi/<zone_id> -
Generic Lookup:
GET /aqi/zone/{zone_id} -
Many Zones at Once:
GET /aqi/zones?ids=srinagar,lehThe same payload as the generic lookup for every zone inids, or for all zones whenidsis left out, as{"zones": [...]}. Zones that fail are left out of the list. -
List All Zones:
GET /zones -
Hardware Sensor Metadata:
GET /sensor-info -
Health Check:
GET /healthReports whether the database and Redis are reachable. Returns503with"status": "degraded"if either is down. -
Seasonal Climatology:
GET /seasonal/{zone_id}Returns 12 monthly entries with typical PM2.5, PM10, AQI, rainfall (mm), and temperature for the zone, plus the current month and season label. Backed by Open-Meteo reanalysis (2022 to present). If a month has at least 200 ground sensor readings, its entry also includes the sensor averages (sensor_pm2_5,sensor_pm10). These sit alongside the reanalysis values rather than being blended into them. -
Weather History:
GET /weather-history/{zone_id}/{time_range}/{interval}Returns time buckets tagged with a weather condition (rain,snow,fog,thunderstorm,clear,cloudy) and precipitation totals, aligned with/historical-databucketing so clients can filter AQI history by weather. Example:/weather-history/srinagar/1w/1h. Also takes the calendar windows described below. Buckets start atanchor + n * interval, andanchoris0for rolling ranges. Takes?limit=and?cursor=the same way as/historical-data. -
Historical Data:
GET /historical-data/{location}/{time_range}/{interval}/{metrics}?format=json|csv&limit=&cursor=Streams historical downsampled sensor readings. Supports memory-safe CSV or JSON streaming, fast-lane rollups (for 15m intervals), and standard Cache-Control headers to protect the DB from heavy loads. Example:/historical-data/jammu_city/30d/15m/pm2.5,pm10?format=json. Passlimit(1 to 10,000) to get one page of buckets instead of the whole stream, withnext_cursorin the JSON (or anX-Next-Cursorheader for CSV) to pass back ascursorfor the next page. It'snullon the last page. -
Calendar Windows:
time_rangeon/historical-dataand/weather-historyalso takes a fixed window instead of a rolling duration. Dates are read in IST, buckets are counted from the start of the window, and a malformed or backwards window returns400.- Month:
2026-10 - ISO week (Monday to Sunday):
2026-W42 - Day:
2026-10-15 - Span of days, both ends included:
2026-10-01_2026-10-07
Example:
/historical-data/jammu_city/2026-W42/1h/pm2.5,pm10?format=json - Month:
The project is designed to be data-driven. Adding or modifying zones (e.g., converting a zone from satellite to physical AirGradient sensors) does not require changing Python code:
- Update
zones.json: Change the zone'sprovider(e.g., from"openmeteo"to"airgradient"). - Update
nodes.json: Map thezone_idto its AirGradient API token environment variable (token_env_var) and list of physical sensor location IDs. Atoken_env_varcontainingPUBLIC(e.g.PUBLIC_AIRGRADIENT_TOKEN) reads the node from AirGradient's public feed, which needs no token. - Update
sensor_info.json: Add the physical sensor metadata to expose it correctly on frontend maps.
Similarly, if government standards change, updating aqi_breakpoints.json will instantly update the calculation logic across the entire application.