Air Quality Index Badge

WHAT IT DOES

This script displays a floating badge showing the current Air Quality Index (AQI) for your location using free public APIs (AQICN or OpenAQ). The badge shows the AQI value with color-coded health risk levels—green for Good, yellow for Moderate, orange for Unhealthy for Sensitive Groups, red for Unhealthy, purple for Very Unhealthy, and maroon for Hazardous. Click the badge to open a detailed overlay with the risk level, location, and a breakdown of pollutants (PM2.5, PM10, O3, NO2, SO2, CO). The badge updates automatically at a configurable interval, keeping you informed about the air quality wherever you browse.

WHERE IT RUNS

The script works on any website—browsing, working, or researching. The badge stays visible as you navigate between pages, providing a persistent air quality reference. It works on any website regardless of framework, and per-site memory remembers your badge position on each domain. The script uses your device's geolocation or a manually entered city to fetch local AQI data.

HOW TO USE

After installation, the badge appears automatically in your chosen corner. Click the badge to open the detailed overlay showing the AQI value, risk level, location, and pollutant breakdown. Open the panel to customize: enable or disable the badge, choose badge position (top-right, top-left, bottom-right, bottom-left), set refresh interval (60-3600 seconds), toggle auto-detection of location or enter a manual city (e.g., "London" or "51.5,-0.1"), choose between AQICN and OpenAQ APIs, toggle pollutant display and risk level display, select dark or light theme, and enable per-site memory. Click "Refresh Now" to manually fetch the latest AQI data.

TECHNICAL MECHANISM

The script uses a multi-stage AQI data pipeline. First, it determines the location using the Geolocation API (if enabled) or the manual location string. Second, it constructs a request to the selected API—AQICN uses the feed endpoint with a token, and OpenAQ uses the latest endpoint. Third, it sends the request using GM_xmlhttpRequest and parses the JSON response. Fourth, it extracts the AQI value, city name, and pollutant data from the response. Fifth, it maps the AQI value to a risk level using the standard EPA scale (0-50 Good, 51-100 Moderate, 101-150 Unhealthy for Sensitive, 151-200 Unhealthy, 201-300 Very Unhealthy, 301+ Hazardous). Sixth, it renders the badge with the AQI value and a color-coded border, and the overlay with detailed information. Seventh, it updates the display at the configured refresh interval using setInterval. The script handles errors gracefully with fallback messages.

THE PANEL

The settings panel is fully draggable and can be positioned anywhere on your screen. It automatically snaps to the nearest edge when released, keeping your workspace organized. The panel can be collapsed to a small bubble showing only a gear icon, and restored with a single click. Its position is remembered across page reloads using GM_setValue. The panel also responds to the Escape key, which instantly hides it until you click the bubble again. All settings are saved immediately when changed and persist across browser sessions.

PLEASE NOTE

This script requires the free BotGentz extension to run. AQI data is fetched from public APIs which may have rate limits or occasional downtime. The script uses the free AQICN token provided in the source code—if you experience issues, you can obtain your own token from waqi.info. Geolocation requires user permission. The script does not access, store, or transmit any personal data or browsing history. All processing happens locally in your browser and never leaves your device.