Air Quality Data Sources

The air-quality repository utilizes external APIs to gather the necessary data for reporting air quality. Two distinct APIs are present in the codebase: the IQAir (formerly AirVisual) API, which is central to the operational Telegram bot, and the OpenWeatherMap API, explored in a separate script for alternative air pollution data processing.

IQAir (AirVisual) API

The primary source of air quality data for the Telegram bot, as implemented in bot.py and bot_refactor_test.py, is the IQAir (AirVisual) API. This API provides real-time air quality information for cities worldwide.

• Purpose: The bot specifically queries the AirVisual API to obtain the current air quality status for Phnom Penh, Cambodia. This data forms the basis for all the bot's scheduled updates and advice messages.
• Key Data Points: From the API response, the bot extracts two critical pieces of information:
  • aqius: The Air Quality Index (AQI) value, calculated according to the US EPA standard. This numerical value is directly used to categorize air quality (e.g., "good," "moderate," "unhealthy").
  • mainus: The main pollutant contributing to the aqius value (e.g., PM2.5, O3).
• API Call Structure: The bot constructs its API requests in a format similar to this (API key placeholder used for security):

  http://api.airvisual.com/v2/city?city=Phnom Penh&state=Phnom Penh&country=Cambodia&key={API_KEY}
  

  As detailed in the [Bot Core Logic and Scheduling] page, the Main class's get_phnom_penh_aq method handles these requests, including retry logic to ensure data retrieval reliability.

OpenWeatherMap API (Alternative Exploration)

The openweather.py script in the repository explores an alternative method for fetching and processing air pollution data using the OpenWeatherMap API. It is important to note that this script is present for exploration and testing purposes and is not currently integrated into the operational Telegram bot's main loop.

• Purpose: The openweather.py script aims to fetch raw air pollution component data (concentrations of various gases and particulates) from the OpenWeatherMap API for a given latitude and longitude.
• Data Points and Custom Calculation: Unlike the AirVisual API, which provides a pre-calculated aqius, the OpenWeatherMap API provides concentrations of individual pollutants. The script then attempts to calculate a composite AQI based on these components:
  • pm2_5: Particulate matter less than 2.5 micrometers.
  • pm10: Particulate matter less than 10 micrometers.
  • o3: Ozone.
  • no2: Nitrogen dioxide.
  • so2: Sulfur dioxide.
  • co: Carbon monoxide.
  • nh3: Ammonia (though often handled separately or with different standards). The script defines a custom breakpoint system and conversion_factor for each pollutant, intending to map their concentrations to an AQI category and calculate a sub-index. The index_calulator and aqi_calculation functions demonstrate an attempt to derive an overall AQI from these individual pollutant measurements.
• API Call Structure: The OpenWeatherMap API requests are structured as follows:

  http://api.openweathermap.org/data/2.5/air_pollution?lat={latitude}&lon={longitude}&appid={API_KEY}
  

API Key Security

Both API interactions rely on sensitive API keys. In the bot.py script, the API_KEY for AirVisual is loaded from an environment variable (os.getenv("API_KEY")), while in bot_refactor_test.py, it's loaded from ./keys.json. Similarly, openweather.py directly embeds the key for demonstration purposes but ideally should also handle it securely. For any deployment, it is crucial to manage these API keys securely, typically by using environment variables or a dedicated configuration management system, and never hardcoding them directly into publicly accessible code.