0
# Air Pollution API
1

2
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.
3

4
## Capabilities
5

6
### Current Air Quality
7

8
Retrieve current air pollution data including AQI and pollutant concentrations.
9

10
```python { .api }
11
class AirPollutionManager:
12
    def airpollution_api_version(self) -> tuple:
13
        """
14
        Get Air Pollution API version.
15
        
16
        Returns:
17
        Tuple representing the API version
18
        """
19
    
20
    def air_quality_at_coords(self, lat: float, lon: float) -> AirStatus:
21
        """
22
        Get current air quality data for coordinates.
23
        
24
        Parameters:
25
        - lat: Latitude (-90.0 to 90.0)
26
        - lon: Longitude (-180.0 to 180.0)
27
        
28
        Returns:
29
        AirStatus object with current air quality data
30
        """
31
```
32

33
### Air Quality Forecasts
34

35
Get air quality forecasts for the next 5 days.
36

37
```python { .api }
38
class AirPollutionManager:
39
    def air_quality_forecast_at_coords(self, lat: float, lon: float) -> List[AirStatus]:
40
        """
41
        Get air quality forecast for coordinates.
42
        
43
        Parameters:
44
        - lat: Latitude (-90.0 to 90.0)
45
        - lon: Longitude (-180.0 to 180.0)
46
        
47
        Returns:
48
        List of AirStatus objects for forecasted air quality
49
        """
50
```
51

52
### Historical Air Quality
53

54
Retrieve historical air pollution data for any time period.
55

56
```python { .api }
57
class AirPollutionManager:
58
    def air_quality_history_at_coords(self, lat: float, lon: float, start, end=None) -> List[AirStatus]:
59
        """
60
        Get historical air quality data for coordinates.
61
        
62
        Parameters:
63
        - lat: Latitude (-90.0 to 90.0)
64
        - lon: Longitude (-180.0 to 180.0)
65
        - start: Start time (UNIX timestamp, datetime, or ISO8601 string)
66
        - end: End time (optional, defaults to current time)
67
        
68
        Returns:
69
        List of AirStatus objects for historical air quality
70
        """
71
```
72

73
### Deprecated Methods (Legacy API)
74

75
**Note**: These methods are deprecated and will be removed in PyOWM v4.0. Use the new air quality methods above instead.
76

77
```python { .api }
78
class AirPollutionManager:
79
    def coindex_around_coords(self, lat: float, lon: float, start=None, interval=None):
80
        """
81
        Get CO index data (deprecated).
82
        
83
        Parameters:
84
        - lat: Latitude (-90.0 to 90.0)
85
        - lon: Longitude (-180.0 to 180.0)
86
        - start: Start time (optional)
87
        - interval: Time interval (optional)
88
        
89
        Returns:
90
        COIndex object with CO pollution data
91
        """
92
    
93
    def ozone_around_coords(self, lat: float, lon: float, start=None, interval=None):
94
        """
95
        Get ozone data (deprecated).
96
        
97
        Parameters:
98
        - lat: Latitude (-90.0 to 90.0)
99
        - lon: Longitude (-180.0 to 180.0)
100
        - start: Start time (optional)
101
        - interval: Time interval (optional)
102
        
103
        Returns:
104
        Ozone object with ozone pollution data
105
        """
106
    
107
    def no2index_around_coords(self, lat: float, lon: float, start=None, interval=None):
108
        """
109
        Get NO2 index data (deprecated).
110
        
111
        Parameters:
112
        - lat: Latitude (-90.0 to 90.0)
113
        - lon: Longitude (-180.0 to 180.0)
114
        - start: Start time (optional)
115
        - interval: Time interval (optional)
116
        
117
        Returns:
118
        NO2Index object with NO2 pollution data
119
        """
120
    
121
    def so2index_around_coords(self, lat: float, lon: float, start=None, interval=None):
122
        """
123
        Get SO2 index data (deprecated).
124
        
125
        Parameters:
126
        - lat: Latitude (-90.0 to 90.0)
127
        - lon: Longitude (-180.0 to 180.0)
128
        - start: Start time (optional)
129
        - interval: Time interval (optional)
130
        
131
        Returns:
132
        SO2Index object with SO2 pollution data
133
        """
134
```
135

136
## Usage Examples
137

138
### Current Air Quality
139

140
```python
141
from pyowm import OWM
142

143
owm = OWM('your-api-key')
144
air_mgr = owm.airpollution_manager()
145

146
# Get current air quality for London
147
air_status = air_mgr.air_quality_at_coords(51.5074, -0.1278)
148

149
# Air Quality Index (1=Good, 2=Fair, 3=Moderate, 4=Poor, 5=Very Poor)
150
aqi = air_status.air_quality_data['main']['aqi']
151
print(f"Air Quality Index: {aqi}")
152

153
# Pollutant concentrations (μg/m³)
154
components = air_status.air_quality_data['components']
155
print(f"CO: {components['co']} μg/m³")
156
print(f"NO₂: {components['no2']} μg/m³")
157
print(f"O₃: {components['o3']} μg/m³")
158
print(f"SO₂: {components['so2']} μg/m³")
159
print(f"PM2.5: {components['pm2_5']} μg/m³")
160
print(f"PM10: {components['pm10']} μg/m³")
161
print(f"NH₃: {components['nh3']} μg/m³")
162

163
print(f"Measurement time: {air_status.reference_time('iso')}")
164
print(f"Location: {air_status.location.name}")
165
```
166

167
### Air Quality Forecast
168

169
```python
170
# Get 5-day air quality forecast
171
forecast = air_mgr.air_quality_forecast_at_coords(40.7128, -74.0060)  # New York
172

173
print(f"Air quality forecast for next {len(forecast)} periods:")
174
for air_status in forecast:
175
    aqi = air_status.air_quality_data['main']['aqi']
176
    pm25 = air_status.air_quality_data['components']['pm2_5']
177
    print(f"{air_status.reference_time('iso')}: AQI={aqi}, PM2.5={pm25} μg/m³")
178
```
179

180
### Historical Air Quality
181

182
```python
183
from datetime import datetime, timedelta
184

185
# Get air quality for the past week
186
end_time = datetime.now()
187
start_time = end_time - timedelta(days=7)
188

189
history = air_mgr.air_quality_history_at_coords(
190
    lat=35.6762, lon=139.6503,  # Tokyo
191
    start=start_time,
192
    end=end_time
193
)
194

195
print(f"Historical air quality data: {len(history)} measurements")
196

197
# Analyze air quality trends
198
aqi_values = [status.air_quality_data['main']['aqi'] for status in history]
199
avg_aqi = sum(aqi_values) / len(aqi_values)
200
max_aqi = max(aqi_values)
201
min_aqi = min(aqi_values)
202

203
print(f"Average AQI: {avg_aqi:.1f}")
204
print(f"Best air quality (lowest AQI): {min_aqi}")
205
print(f"Worst air quality (highest AQI): {max_aqi}")
206
```
207

208
## Data Types
209

210
```python { .api }
211
class AirStatus:
212
    def __init__(self, reference_time: int, location: Location, air_quality_data: dict, reception_time: int): ...
213
    
214
    def reference_time(self, timeformat: str = 'unix') -> Union[int, str, datetime]:
215
        """
216
        Get measurement reference time.
217
        
218
        Parameters:
219
        - timeformat: 'unix', 'iso', or 'date'
220
        
221
        Returns:
222
        Timestamp in requested format
223
        """
224
    
225
    def reception_time(self, timeformat: str = 'unix') -> Union[int, str, datetime]:
226
        """
227
        Get data reception time.
228
        
229
        Parameters:
230
        - timeformat: 'unix', 'iso', or 'date'
231
        
232
        Returns:
233
        Timestamp in requested format
234
        """
235
    
236
    @property
237
    def location(self) -> Location: ...
238
    @property 
239
    def air_quality_data(self) -> dict:
240
        """
241
        Air quality data structure:
242
        {
243
            'main': {
244
                'aqi': int  # Air Quality Index (1-5)
245
            },
246
            'components': {
247
                'co': float,      # Carbon monoxide (μg/m³)
248
                'no': float,      # Nitrogen monoxide (μg/m³)
249
                'no2': float,     # Nitrogen dioxide (μg/m³)
250
                'o3': float,      # Ozone (μg/m³)
251
                'so2': float,     # Sulphur dioxide (μg/m³)
252
                'pm2_5': float,   # Fine particles matter (μg/m³)
253
                'pm10': float,    # Coarse particulate matter (μg/m³)
254
                'nh3': float      # Ammonia (μg/m³)
255
            }
256
        }
257
        """
258
    
259
    def to_dict(self) -> dict: ...
260
```
261

262
## Air Quality Index Scale
263

264
The Air Quality Index (AQI) provides a standardized way to communicate air quality:
265

266
- **1 - Good**: Air quality is satisfactory, little or no risk
267
- **2 - Fair**: Air quality is acceptable for most people
268
- **3 - Moderate**: Sensitive individuals may experience minor issues
269
- **4 - Poor**: Everyone may experience health effects; sensitive groups more serious effects
270
- **5 - Very Poor**: Health alert, serious health effects for everyone
271

272
## Pollutant Information
273

274
- **CO (Carbon Monoxide)**: Colorless, odorless gas from incomplete combustion
275
- **NO₂ (Nitrogen Dioxide)**: Reddish-brown gas, mainly from vehicle emissions
276
- **O₃ (Ozone)**: Ground-level ozone, formed by reactions of other pollutants
277
- **SO₂ (Sulphur Dioxide)**: Produced by burning fossil fuels containing sulfur
278
- **PM2.5**: Fine particles less than 2.5 micrometers, penetrate deep into lungs
279
- **PM10**: Coarse particles less than 10 micrometers, affect respiratory system
280
- **NH₃ (Ammonia)**: Mainly from agricultural activities and industrial processes