Key Features

Fetches PM2.5 data from a PostgreSQL table (cams_pm25)
Normalizes geographic coordinates for global consistency
Converts PM2.5 to AQI using the US EPA scale
Interpolates AQI values across a geographic grid using IDW via scipy
Generates colored heatmaps using matplotlib and Pillow
Caches results using Redis for performance
Exposes 3 endpoints:
- /aqi-data: returns the interpolated AQI image and bounds
- /invalidate-cache/aqi: deletes current hour's cached image
- /refresh-cache/aqi: regenerates and stores updated cache

Architecture & Workflow

Data Source
The cams_pm25 table contains daily PM2.5 estimates with:
- latitude, longitude: geo-coordinates of grid points
- pm2p5: CAMS-modeled PM2.5 values
- time: timestamp for the forecast
FastAPI Server
FastAPI powers the backend with CORS enabled, allowing secure access from web frontends or apps.
Redis Caching
- Caches interpolated image results by hour to improve performance
- Uses keys like airqo:aqi_overlay:2025-07-19T10
- TTL: 10 minutes (or 1 hour if manually refreshed)
IDW Interpolation
- Uses scipy.interpolate.griddata with the "cubic" method
- Generates a fine-resolution (e.g., 5000×5000) grid image
- Converts PM2.5 to AQI
- Maps AQI values to RGBA color using predefined categories:
  - Green: 0–50
  - Yellow: 51–100
  - Orange: 101–150
  - Red: 151–200
  - Purple: 201–300
  - Maroon: >300
Image Encoding
- Creates an RGBA image using Pillow
- Encodes image as base64 PNG
- Returns JSON with:
  - image: base64 data URL
  - bounds: map extent
  - lat_min, lat_max, lon_min, lon_max
  - generated_at: ISO timestamp

API Endpoints

✅ `/aqi-data` (GET)

Returns interpolated AQI image and bounding coordinates.

json

CopyEdit

{ "mapimage": { "image": "data:image/png;base64,...", "bounds": [[lat_min, lon_min], [lat_max, lon_max]], "lat_min": 1.23, "lat_max": 2.34, "lon_min": 31.12, "lon_max": 32.45 }, "time": { "generated_at": "2025-07-19T10:00:00Z" } }

🔁 `/refresh-cache/aqi` (POST)

Invalidates current cache
Regenerates new interpolated image
Stores it in Redis with a 1-hour TTL

🗑 `/invalidate-cache/aqi` (POST)

Deletes the cached overlay image for the current hour

Technical Highlights

Environment Variables via .env
- PostgreSQL and Redis credentials managed securely
Matplotlib Headless Mode
- matplotlib.use('Agg') allows image generation in servers without GUI
Longitude Normalization
- Ensures values stay within [-180°, 180°] to avoid wraparound issues
PM2.5 → AQI Conversion
- Based on the EPA breakpoints, implemented manually to control mapping accuracy

Performance and Scalability

Redis caching reduces response times significantly
The use of hourly cache keys ensures data freshness while avoiding redundant computation
Image encoding (base64) allows seamless frontend integration

Challenges and Solutions

ChallengeSolutionCAMS data is gridded and coarse (~10 km)Used IDW interpolation to densify dataLarge images slow down APIOptimized with resolution control and Redis cachingGeographic edge artifactsNormalized longitude and clipped image boundariesHigh memory usage at 5000×5000Efficient NumPy vectorization and memory-safe image handling

Future Enhancements

Add support for temporal heatmap series (e.g., hourly or daily)
Integrate multiple pollutants (e.g., O₃, NO₂) with toggles
Create dashboard frontend with Leaflet or Mapbox
Add Kriging and machine learning models for comparative interpolation

Conclusion

This API provides a fast, robust, and scalable solution to visualize air pollution in regions without dense sensor coverage, using publicly available CAMS data. By combining scientific interpolation, dynamic rendering, and caching, the platform makes it easy to monitor, analyze, and respond to air quality conditions in near real-time.

Let me know if you'd like a version of this:

As a PDF or Word document
With images and diagrams
As a README.md for GitHub
Or in a PowerPoint slide format for presentations

Ask ChatGPT

Real-Time PM2.5 Heatmap Generation API using IDW and CAMS Data

Overview

Details

Real-Time PM2.5 Heatmap Generation API using IDW and CAMS Data

Overview

Details