tessl/pypi-pyowm
A comprehensive Python wrapper around OpenWeatherMap web APIs providing weather data, forecasts, air pollution, UV index, and agricultural information
—
Pending
air-pollution.mddocs/
Air Pollution API
Air quality information including Air Quality Index (AQI) and concentrations of pollutants like CO, NO₂, O₃, SO₂, PM2.5, PM10, and NH₃. Provides current air quality conditions, forecasts, and historical air pollution data for any location worldwide.
Capabilities
Current Air Quality
Retrieve current air pollution data including AQI and pollutant concentrations.
class AirPollutionManager:
def airpollution_api_version(self) -> tuple:
"""
Get Air Pollution API version.
Returns:
Tuple representing the API version
"""
def air_quality_at_coords(self, lat: float, lon: float) -> AirStatus:
"""
Get current air quality data for coordinates.
Parameters:
- lat: Latitude (-90.0 to 90.0)
- lon: Longitude (-180.0 to 180.0)
Returns:
AirStatus object with current air quality data
"""Air Quality Forecasts
Get air quality forecasts for the next 5 days.
class AirPollutionManager:
def air_quality_forecast_at_coords(self, lat: float, lon: float) -> List[AirStatus]:
"""
Get air quality forecast for coordinates.
Parameters:
- lat: Latitude (-90.0 to 90.0)
- lon: Longitude (-180.0 to 180.0)
Returns:
List of AirStatus objects for forecasted air quality
"""Historical Air Quality
Retrieve historical air pollution data for any time period.
class AirPollutionManager:
def air_quality_history_at_coords(self, lat: float, lon: float, start, end=None) -> List[AirStatus]:
"""
Get historical air quality data for coordinates.
Parameters:
- lat: Latitude (-90.0 to 90.0)
- lon: Longitude (-180.0 to 180.0)
- start: Start time (UNIX timestamp, datetime, or ISO8601 string)
- end: End time (optional, defaults to current time)
Returns:
List of AirStatus objects for historical air quality
"""Deprecated Methods (Legacy API)
Note: These methods are deprecated and will be removed in PyOWM v4.0. Use the new air quality methods above instead.
class AirPollutionManager:
def coindex_around_coords(self, lat: float, lon: float, start=None, interval=None):
"""
Get CO index data (deprecated).
Parameters:
- lat: Latitude (-90.0 to 90.0)
- lon: Longitude (-180.0 to 180.0)
- start: Start time (optional)
- interval: Time interval (optional)
Returns:
COIndex object with CO pollution data
"""
def ozone_around_coords(self, lat: float, lon: float, start=None, interval=None):
"""
Get ozone data (deprecated).
Parameters:
- lat: Latitude (-90.0 to 90.0)
- lon: Longitude (-180.0 to 180.0)
- start: Start time (optional)
- interval: Time interval (optional)
Returns:
Ozone object with ozone pollution data
"""
def no2index_around_coords(self, lat: float, lon: float, start=None, interval=None):
"""
Get NO2 index data (deprecated).
Parameters:
- lat: Latitude (-90.0 to 90.0)
- lon: Longitude (-180.0 to 180.0)
- start: Start time (optional)
- interval: Time interval (optional)
Returns:
NO2Index object with NO2 pollution data
"""
def so2index_around_coords(self, lat: float, lon: float, start=None, interval=None):
"""
Get SO2 index data (deprecated).
Parameters:
- lat: Latitude (-90.0 to 90.0)
- lon: Longitude (-180.0 to 180.0)
- start: Start time (optional)
- interval: Time interval (optional)
Returns:
SO2Index object with SO2 pollution data
"""Usage Examples
Current Air Quality
from pyowm import OWM
owm = OWM('your-api-key')
air_mgr = owm.airpollution_manager()
# Get current air quality for London
air_status = air_mgr.air_quality_at_coords(51.5074, -0.1278)
# Air Quality Index (1=Good, 2=Fair, 3=Moderate, 4=Poor, 5=Very Poor)
aqi = air_status.air_quality_data['main']['aqi']
print(f"Air Quality Index: {aqi}")
# Pollutant concentrations (μg/m³)
components = air_status.air_quality_data['components']
print(f"CO: {components['co']} μg/m³")
print(f"NO₂: {components['no2']} μg/m³")
print(f"O₃: {components['o3']} μg/m³")
print(f"SO₂: {components['so2']} μg/m³")
print(f"PM2.5: {components['pm2_5']} μg/m³")
print(f"PM10: {components['pm10']} μg/m³")
print(f"NH₃: {components['nh3']} μg/m³")
print(f"Measurement time: {air_status.reference_time('iso')}")
print(f"Location: {air_status.location.name}")Air Quality Forecast
# Get 5-day air quality forecast
forecast = air_mgr.air_quality_forecast_at_coords(40.7128, -74.0060) # New York
print(f"Air quality forecast for next {len(forecast)} periods:")
for air_status in forecast:
aqi = air_status.air_quality_data['main']['aqi']
pm25 = air_status.air_quality_data['components']['pm2_5']
print(f"{air_status.reference_time('iso')}: AQI={aqi}, PM2.5={pm25} μg/m³")Historical Air Quality
from datetime import datetime, timedelta
# Get air quality for the past week
end_time = datetime.now()
start_time = end_time - timedelta(days=7)
history = air_mgr.air_quality_history_at_coords(
lat=35.6762, lon=139.6503, # Tokyo
start=start_time,
end=end_time
)
print(f"Historical air quality data: {len(history)} measurements")
# Analyze air quality trends
aqi_values = [status.air_quality_data['main']['aqi'] for status in history]
avg_aqi = sum(aqi_values) / len(aqi_values)
max_aqi = max(aqi_values)
min_aqi = min(aqi_values)
print(f"Average AQI: {avg_aqi:.1f}")
print(f"Best air quality (lowest AQI): {min_aqi}")
print(f"Worst air quality (highest AQI): {max_aqi}")Data Types
class AirStatus:
def __init__(self, reference_time: int, location: Location, air_quality_data: dict, reception_time: int): ...
def reference_time(self, timeformat: str = 'unix') -> Union[int, str, datetime]:
"""
Get measurement reference time.
Parameters:
- timeformat: 'unix', 'iso', or 'date'
Returns:
Timestamp in requested format
"""
def reception_time(self, timeformat: str = 'unix') -> Union[int, str, datetime]:
"""
Get data reception time.
Parameters:
- timeformat: 'unix', 'iso', or 'date'
Returns:
Timestamp in requested format
"""
@property
def location(self) -> Location: ...
@property
def air_quality_data(self) -> dict:
"""
Air quality data structure:
{
'main': {
'aqi': int # Air Quality Index (1-5)
},
'components': {
'co': float, # Carbon monoxide (μg/m³)
'no': float, # Nitrogen monoxide (μg/m³)
'no2': float, # Nitrogen dioxide (μg/m³)
'o3': float, # Ozone (μg/m³)
'so2': float, # Sulphur dioxide (μg/m³)
'pm2_5': float, # Fine particles matter (μg/m³)
'pm10': float, # Coarse particulate matter (μg/m³)
'nh3': float # Ammonia (μg/m³)
}
}
"""
def to_dict(self) -> dict: ...Air Quality Index Scale
The Air Quality Index (AQI) provides a standardized way to communicate air quality:
- 1 - Good: Air quality is satisfactory, little or no risk
- 2 - Fair: Air quality is acceptable for most people
- 3 - Moderate: Sensitive individuals may experience minor issues
- 4 - Poor: Everyone may experience health effects; sensitive groups more serious effects
- 5 - Very Poor: Health alert, serious health effects for everyone
Pollutant Information
- CO (Carbon Monoxide): Colorless, odorless gas from incomplete combustion
- NO₂ (Nitrogen Dioxide): Reddish-brown gas, mainly from vehicle emissions
- O₃ (Ozone): Ground-level ozone, formed by reactions of other pollutants
- SO₂ (Sulphur Dioxide): Produced by burning fossil fuels containing sulfur
- PM2.5: Fine particles less than 2.5 micrometers, penetrate deep into lungs
- PM10: Coarse particles less than 10 micrometers, affect respiratory system
- NH₃ (Ammonia): Mainly from agricultural activities and industrial processes
Install with Tessl CLI
npx tessl i tessl/pypi-pyowm