0
# PyOWM
1

2
A comprehensive Python wrapper around OpenWeatherMap web APIs providing weather data, forecasts, air pollution, UV index, and agricultural information. PyOWM offers a simple object model with human-friendly interfaces for accessing current weather conditions, weather forecasts, historical data, geocoding services, weather alerts, and satellite imagery across both free and paid OpenWeatherMap API subscription plans.
3

4
## Package Information
5

6
- **Package Name**: pyowm
7
- **Language**: Python
8
- **Installation**: `pip install pyowm`
9
- **Python Version**: 3.9+
10

11
## Core Imports
12

13
```python
14
from pyowm import OWM
15
```
16

17
For specific managers and data models:
18

19
```python
20
from pyowm.owm import OWM
21
from pyowm.weatherapi30.weather import Weather
22
from pyowm.weatherapi30.location import Location
23
```
24

25
## Basic Usage
26

27
```python
28
from pyowm import OWM
29

30
# Initialize with your API key
31
owm = OWM('your-api-key-here')
32

33
# Get current weather for a location
34
mgr = owm.weather_manager()
35
observation = mgr.weather_at_place('London,GB')
36
weather = observation.weather
37

38
print(f"Temperature: {weather.temperature('celsius')['temp']}°C")
39
print(f"Status: {weather.detailed_status}")
40
print(f"Wind: {weather.wind()}")
41

42
# Get weather forecast
43
forecaster = mgr.forecast_at_place('London,GB', '3h')
44
forecast = forecaster.forecast
45

46
print(f"Forecast items: {len(forecast)}")
47
for weather in forecast[:3]:  # First 3 forecast items
48
    print(f"{weather.reference_time('iso')}: {weather.status}")
49

50
# Get air quality data
51
air_mgr = owm.airpollution_manager()
52
air_status = air_mgr.air_quality_at_coords(51.5074, -0.1278)
53
print(f"Air Quality Index: {air_status.air_quality_data['main']['aqi']}")
54
```
55

56
## Architecture
57

58
PyOWM follows a manager-based architecture where the main `OWM` class serves as a factory for specialized API managers:
59

60
- **OWM**: Central entry point providing factory methods for all API managers
61
- **API Managers**: Specialized classes for each OpenWeatherMap API (Weather, Air Pollution, Agro, etc.)
62
- **Data Models**: Rich objects representing weather data, locations, forecasts, and other domain entities
63
- **Utilities**: Helper functions for unit conversion, time formatting, and geographic operations
64
- **Configuration System**: Flexible configuration supporting multiple subscription types and proxy settings
65

66
This design enables clean separation of concerns while providing a unified interface to OpenWeatherMap's diverse API ecosystem.
67

68
## Capabilities
69

70
### Weather Data and Forecasts
71

72
Current weather conditions, forecasts, and historical data from OpenWeatherMap's Weather API and OneCall API. Supports location-based queries by name, coordinates, city ID, or zip code.
73

74
```python { .api }
75
class WeatherManager:
76
    def weather_api_version(self) -> tuple: ...
77
    def weather_at_place(self, name: str) -> Observation: ...
78
    def weather_at_coords(self, lat: float, lon: float) -> Observation: ...
79
    def weather_at_zip_code(self, zipcode: str, country: str) -> Observation: ...
80
    def weather_at_id(self, id: int) -> Observation: ...
81
    def weather_at_ids(self, ids_list: List[int]) -> List[Observation]: ...
82
    def weather_at_places(self, pattern: str, searchtype: str, limit: int = None) -> List[Observation]: ...
83
    def weather_at_places_in_bbox(self, lon_left: float, lat_bottom: float, lon_right: float, lat_top: float, zoom: int = 10, cluster: bool = False) -> List[Observation]: ...
84
    def weather_around_coords(self, lat: float, lon: float, limit: int = None) -> List[Observation]: ...
85
    def forecast_at_place(self, name: str, interval: str, limit: int = None) -> Forecaster: ...
86
    def forecast_at_coords(self, lat: float, lon: float, interval: str, limit: int = None) -> Forecaster: ...
87
    def forecast_at_id(self, id: int, interval: str, limit: int = None) -> Forecaster: ...
88
    def one_call(self, lat: Union[int, float], lon: Union[int, float], **kwargs) -> OneCall: ...
89
    def one_call_history(self, lat: Union[int, float], lon: Union[int, float], dt: int = None) -> OneCall: ...
90
    def station_tick_history(self, station_ID: int, limit: int = None) -> Historian: ...
91
    def station_hour_history(self, station_ID: int, limit: int = None) -> Historian: ...
92
    def station_day_history(self, station_ID: int, limit: int = None) -> Historian: ...
93
```
94

95
[Weather API](./weather.md)
96

97
### Air Pollution Data
98

99
Air quality information including AQI (Air Quality Index) and concentrations of pollutants like CO, NO₂, O₃, SO₂, PM2.5, PM10, and NH₃.
100

101
```python { .api }
102
class AirPollutionManager:
103
    def airpollution_api_version(self) -> tuple: ...
104
    def air_quality_at_coords(self, lat: float, lon: float) -> AirStatus: ...
105
    def air_quality_forecast_at_coords(self, lat: float, lon: float) -> List[AirStatus]: ...
106
    def air_quality_history_at_coords(self, lat: float, lon: float, start, end=None) -> List[AirStatus]: ...
107
```
108

109
[Air Pollution API](./air-pollution.md)
110

111
### Agricultural Data
112

113
Satellite imagery, soil data, and agricultural information for polygonal areas including NDVI, EVI indices and soil temperature/moisture data.
114

115
```python { .api }
116
class AgroManager:
117
    def agro_api_version(self) -> tuple: ...
118
    def create_polygon(self, geopolygon: GeoPolygon, name: str = None) -> Polygon: ...
119
    def get_polygons(self) -> List[Polygon]: ...
120
    def get_polygon(self, polygon_id: str) -> Polygon: ...
121
    def update_polygon(self, polygon: Polygon) -> Polygon: ...
122
    def delete_polygon(self, polygon: Polygon) -> None: ...
123
    def soil_data(self, polygon_id: str) -> Soil: ...
124
    def search_satellite_imagery(self, polygon_id: str, acquired_from: int, acquired_to: int, img_w: int = None, img_h: int = None) -> SatelliteImagerySearchResultSet: ...
125
    def download_satellite_image(self, satellite_image: SatelliteImage, preset: str, palette: str = None): ...
126
```
127

128
[Agricultural API](./agro.md)
129

130
### Weather Alerts and Triggers
131

132
Weather alert system allowing creation of triggers that monitor weather conditions and fire alerts when specified criteria are met.
133

134
```python { .api }
135
class AlertManager:
136
    def alert_api_version(self) -> tuple: ...
137
    def create_trigger(self, start, end, conditions, area, alert_channels=None) -> Trigger: ...
138
    def get_triggers(self) -> List[Trigger]: ...
139
    def get_trigger(self, trigger_id: str) -> Trigger: ...
140
    def update_trigger(self, trigger: Trigger) -> Trigger: ...
141
    def delete_trigger(self, trigger: Trigger) -> None: ...
142
    def get_alerts_for(self, trigger: Trigger, since: int = None) -> List[Alert]: ...
143
    def delete_all_alerts_for(self, trigger: Trigger) -> None: ...
144
```
145

146
[Weather Alerts](./alerts.md)
147

148
### Weather Station Management
149

150
Personal weather station management for creating, updating stations and sending/retrieving measurement data.
151

152
```python { .api }
153
class StationsManager:
154
    def stations_api_version(self) -> tuple: ...
155
    def get_stations(self) -> List[Station]: ...
156
    def get_station(self, id: str) -> Station: ...
157
    def create_station(self, external_id: str, name: str, lat: float, lon: float, alt: float = None) -> Station: ...
158
    def update_station(self, station: Station) -> None: ...
159
    def delete_station(self, station: Station) -> None: ...
160
    def send_measurement(self, measurement: Measurement) -> None: ...
161
    def send_measurements(self, list_of_measurements: List[Measurement]) -> None: ...
162
    def get_measurements(self, station_id: str, aggregated_on: str, from_timestamp: int, to_timestamp: int, limit: int = 100) -> List[AggregatedMeasurement]: ...
163
    def send_buffer(self, buffer: Buffer) -> None: ...
164
```
165

166
[Weather Stations](./stations.md)
167

168
### UV Index Data
169

170
Ultraviolet radiation index information including current UV levels, forecasts, and historical UV index data.
171

172
```python { .api }
173
class UVIndexManager:
174
    def uvindex_api_version(self) -> tuple: ...
175
    def uvindex_around_coords(self, lat: float, lon: float) -> UVIndex: ...
176
    def uvindex_forecast_around_coords(self, lat: float, lon: float) -> List[UVIndex]: ...
177
    def uvindex_history_around_coords(self, lat: float, lon: float, start, end=None) -> List[UVIndex]: ...
178
```
179

180
[UV Index API](./uv-index.md)
181

182
### Geocoding Services
183

184
Direct and reverse geocoding for converting between place names and geographic coordinates.
185

186
```python { .api }
187
class GeocodingManager:
188
    def geocoding_api_version(self) -> tuple: ...
189
    def geocode(self, toponym: str, country: str = None, state_code: str = None, limit: int = None) -> List[Location]: ...
190
    def reverse_geocode(self, lat: float, lon: float, limit: int = None) -> List[Location]: ...
191
```
192

193
[Geocoding API](./geocoding.md)
194

195
### Map Tiles
196

197
Weather map tiles for visualization including precipitation, wind, temperature, and pressure layers.
198

199
```python { .api }
200
class TileManager:
201
    def get_tile(self, x: int, y: int, zoom: int) -> Tile: ...
202
```
203

204
[Map Tiles](./tiles.md)
205

206
## Core Types
207

208
```python { .api }
209
class OWM:
210
    def __init__(self, api_key: str, config: dict = None): ...
211
    
212
    @property
213
    def configuration(self) -> dict: ...
214
    @property
215
    def version(self) -> tuple: ...
216
    @property
217
    def supported_languages(self) -> List[str]: ...
218
    
219
    def weather_manager(self) -> WeatherManager: ...
220
    def airpollution_manager(self) -> AirPollutionManager: ...
221
    def agro_manager(self) -> AgroManager: ...
222
    def alert_manager(self) -> AlertManager: ...
223
    def stations_manager(self) -> StationsManager: ...
224
    def uvindex_manager(self) -> UVIndexManager: ...
225
    def geocoding_manager(self) -> GeocodingManager: ...
226
    def tile_manager(self, layer_name: str) -> TileManager: ...
227
    def city_id_registry(self) -> CityIDRegistry: ...
228

229
class Location:
230
    def __init__(self, name: str, lon: Union[int, float], lat: Union[int, float], _id: int, country: str = None): ...
231
    
232
    @property
233
    def name(self) -> str: ...
234
    @property
235
    def lon(self) -> Union[int, float]: ...
236
    @property
237
    def lat(self) -> Union[int, float]: ...
238
    @property
239
    def id(self) -> int: ...
240
    @property
241
    def country(self) -> str: ...
242
    
243
    def to_geopoint(self) -> Point: ...
244
    def to_dict(self) -> dict: ...
245

246
class Weather:
247
    def reference_time(self, timeformat: str = 'unix') -> Union[int, str, datetime]: ...
248
    def sunset_time(self, timeformat: str = 'unix') -> Union[int, str, datetime, None]: ...
249
    def sunrise_time(self, timeformat: str = 'unix') -> Union[int, str, datetime, None]: ...
250
    def wind(self, unit: str = 'meters_sec') -> dict: ...
251
    def temperature(self, unit: str = 'kelvin') -> dict: ...
252
    def barometric_pressure(self, unit: str = 'hPa') -> dict: ...
253
    def visibility(self, unit: str = 'meters') -> float: ...
254
    def weather_icon_url(self, size: str = "") -> str: ...
255
    
256
    @property
257
    def status(self) -> str: ...
258
    @property
259
    def detailed_status(self) -> str: ...
260
    @property
261
    def weather_code(self) -> int: ...
262
    @property
263
    def weather_icon_name(self) -> str: ...
264
    @property
265
    def clouds(self) -> int: ...
266
    @property
267
    def rain(self) -> dict: ...
268
    @property
269
    def snow(self) -> dict: ...
270
    @property
271
    def humidity(self) -> int: ...
272
    @property
273
    def dewpoint(self) -> float: ...
274
    @property
275
    def heat_index(self) -> float: ...
276
    @property
277
    def humidex(self) -> float: ...
278
    @property
279
    def visibility_distance(self) -> float: ...
280
    @property
281
    def uvi(self) -> Union[int, float, None]: ...
282
    @property
283
    def precipitation_probability(self) -> Union[float, None]: ...
284

285
class Observation:
286
    def __init__(self, reception_time: int, location: Location, weather: Weather): ...
287
    
288
    def reception_time(self, timeformat: str = 'unix') -> Union[int, str, datetime]: ...
289
    
290
    @property
291
    def location(self) -> Location: ...
292
    @property
293
    def weather(self) -> Weather: ...
294

295
class Forecast:
296
    def __init__(self, interval: str, reception_time: int, location: Location, weathers: List[Weather]): ...
297
    
298
    def get(self, index: int) -> Weather: ...
299
    def reception_time(self, timeformat: str = 'unix') -> Union[int, str, datetime]: ...
300
    def actualize(self) -> None: ...
301
    
302
    @property
303
    def interval(self) -> str: ...
304
    @property
305
    def location(self) -> Location: ...
306
    @property
307
    def weathers(self) -> List[Weather]: ...
308
    
309
    def __len__(self) -> int: ...
310
    def __iter__(self): ...
311

312
class Forecaster:
313
    def __init__(self, forecast: Forecast): ...
314
    
315
    def when_starts(self, timeformat: str = 'unix') -> Union[int, str, datetime]: ...
316
    def when_ends(self, timeformat: str = 'unix') -> Union[int, str, datetime]: ...
317
    
318
    def will_have_rain(self) -> bool: ...
319
    def will_have_clear(self) -> bool: ...
320
    def will_have_fog(self) -> bool: ...
321
    def will_have_clouds(self) -> bool: ...
322
    def will_have_snow(self) -> bool: ...
323
    def will_have_storm(self) -> bool: ...
324
    def will_have_tornado(self) -> bool: ...
325
    def will_have_hurricane(self) -> bool: ...
326
    
327
    def when_rain(self) -> List[Weather]: ...
328
    def when_clear(self) -> List[Weather]: ...
329
    def when_fog(self) -> List[Weather]: ...
330
    def when_clouds(self) -> List[Weather]: ...
331
    def when_snow(self) -> List[Weather]: ...
332
    def when_storm(self) -> List[Weather]: ...
333
    def when_tornado(self) -> List[Weather]: ...
334
    def when_hurricane(self) -> List[Weather]: ...
335
    
336
    def will_be_rainy_at(self, timeobject) -> bool: ...
337
    def will_be_clear_at(self, timeobject) -> bool: ...
338
    def will_be_snowy_at(self, timeobject) -> bool: ...
339
    def will_be_cloudy_at(self, timeobject) -> bool: ...
340
    def will_be_foggy_at(self, timeobject) -> bool: ...
341
    def will_be_stormy_at(self, timeobject) -> bool: ...
342
    def will_be_tornado_at(self, timeobject) -> bool: ...
343
    def will_be_hurricane_at(self, timeobject) -> bool: ...
344
    
345
    def get_weather_at(self, timeobject) -> Weather: ...
346
    
347
    def most_hot(self) -> Union[Weather, None]: ...
348
    def most_cold(self) -> Union[Weather, None]: ...
349
    def most_humid(self) -> Union[Weather, None]: ...
350
    def most_rainy(self) -> Union[Weather, None]: ...
351
    def most_snowy(self) -> Union[Weather, None]: ...
352
    def most_windy(self) -> Union[Weather, None]: ...
353
    
354
    @property
355
    def forecast(self) -> Forecast: ...
356

357
class OneCall:
358
    def __init__(self, lat: Union[int, float], lon: Union[int, float], timezone: str, 
359
                 current: Weather, forecast_minutely: Optional[List[Weather]] = None,
360
                 forecast_hourly: Optional[List[Weather]] = None, 
361
                 forecast_daily: Optional[List[Weather]] = None,
362
                 national_weather_alerts: Optional[List] = None): ...
363
    
364
    def to_geopoint(self) -> Point: ...
365
    
366
    @property
367
    def lat(self) -> Union[int, float]: ...
368
    @property
369
    def lon(self) -> Union[int, float]: ...
370
    @property
371
    def timezone(self) -> str: ...
372
    @property
373
    def current(self) -> Weather: ...
374
    @property
375
    def forecast_minutely(self) -> Optional[List[Weather]]: ...
376
    @property
377
    def forecast_hourly(self) -> Optional[List[Weather]]: ...
378
    @property
379
    def forecast_daily(self) -> Optional[List[Weather]]: ...
380
    @property
381
    def national_weather_alerts(self) -> Optional[List]: ...
382

383
class Historian:
384
    def __init__(self, station_history): ...
385
    
386
    def temperature_series(self, unit: str = 'kelvin') -> List[Tuple[int, float]]: ...
387
    def humidity_series(self) -> List[Tuple[int, int]]: ...
388
    def pressure_series(self) -> List[Tuple[int, float]]: ...
389
    def rain_series(self) -> List[Tuple[int, float]]: ...
390
    def wind_series(self) -> List[Tuple[int, dict]]: ...
391
    
392
    def max_temperature(self, unit: str = 'kelvin') -> Tuple[int, float]: ...
393
    def min_temperature(self, unit: str = 'kelvin') -> Tuple[int, float]: ...
394
    def average_temperature(self, unit: str = 'kelvin') -> float: ...
395
    def max_humidity(self) -> Tuple[int, int]: ...
396
    def min_humidity(self) -> Tuple[int, int]: ...
397
    def average_humidity(self) -> float: ...
398
    def max_pressure(self) -> Tuple[int, float]: ...
399
    def min_pressure(self) -> Tuple[int, float]: ...
400
    def average_pressure(self) -> float: ...
401
    def max_rain(self) -> Tuple[int, float]: ...
402
    def min_rain(self) -> Tuple[int, float]: ...
403
    def average_rain(self) -> float: ...
404

405
class AirStatus:
406
    def __init__(self, reference_time: int, location: Location, air_quality_data: dict, reception_time: int): ...
407
    
408
    def reference_time(self, timeformat: str = 'unix') -> Union[int, str, datetime]: ...
409
    def reception_time(self, timeformat: str = 'unix') -> Union[int, str, datetime]: ...
410
    
411
    @property
412
    def location(self) -> Location: ...
413
    @property
414
    def air_quality_data(self) -> dict: ...
415
    @property
416
    def aqi(self): ...
417
    @property
418
    def co(self): ...
419
    @property
420
    def no(self): ...
421
    @property
422
    def no2(self): ...
423
    @property
424
    def o3(self): ...
425
    @property
426
    def so2(self): ...
427
    @property
428
    def pm2_5(self): ...
429
    @property
430
    def pm10(self): ...
431
    @property
432
    def nh3(self): ...
433

434
class UVIndex:
435
    def __init__(self, reference_time: int, location: Location, value: float, reception_time: int): ...
436
    
437
    def reference_time(self, timeformat: str = 'unix') -> Union[int, str, datetime]: ...
438
    def reception_time(self, timeformat: str = 'unix') -> Union[int, str, datetime]: ...
439
    def get_exposure_risk(self) -> str: ...
440
    
441
    @property
442
    def location(self) -> Location: ...
443
    @property
444
    def value(self) -> float: ...
445
```
446

447
## Configuration
448

449
```python { .api }
450
# Default configuration
451
from pyowm.utils.config import get_default_config, get_default_config_for_subscription_type, get_default_config_for_proxy
452

453
def get_default_config() -> dict: ...
454
def get_default_config_for_subscription_type(name: str) -> dict: ...
455
def get_default_config_for_proxy(http_url: str, https_url: str) -> dict: ...
456

457
# Subscription types
458
from pyowm.commons.enums import SubscriptionTypeEnum
459

460
class SubscriptionTypeEnum:
461
    FREE: SubscriptionType
462
    STARTUP: SubscriptionType
463
    DEVELOPER: SubscriptionType
464
    PROFESSIONAL: SubscriptionType
465
    ENTERPRISE: SubscriptionType
466
```
467

468
## Error Handling
469

470
PyOWM provides a comprehensive exception hierarchy for robust error handling:
471

472
```python { .api }
473
from pyowm.commons.exceptions import (
474
    PyOWMError,               # Base exception
475
    APIRequestError,          # Network/infrastructure failures
476
    APIResponseError,         # HTTP error status codes
477
    NotFoundError,           # Entity not found
478
    UnauthorizedError,       # Insufficient subscription capabilities
479
    ParseAPIResponseError,   # JSON parsing failures
480
    TimeoutError,            # Response timeout
481
    BadGatewayError,         # Upstream backend issues
482
    InvalidSSLCertificateError  # SSL certificate verification failure
483
)
484
```
485

486
## Utilities
487

488
```python { .api }
489
# Geographic utilities
490
from pyowm.utils.geo import Point, Polygon, assert_is_lat, assert_is_lon
491

492
class Point:
493
    def __init__(self, lon: Union[int, float], lat: Union[int, float]): ...
494
    def bounding_square_polygon(self, inscribed_circle_radius_km: float = 10.0) -> Polygon: ...
495

496
# Unit conversions
497
from pyowm.utils.measurables import (
498
    kelvin_to_celsius, celsius_to_fahrenheit,
499
    meters_sec_to_miles_hour, meters_sec_to_knots,
500
    hPa_to_inHg, hPa_to_mmHg
501
)
502

503
# Time utilities  
504
from pyowm.utils.timestamps import to_UNIXtime, to_ISO
505

506
# City ID registry
507
class CityIDRegistry:
508
    def ids_for(self, city_name: str, country: str = None, state: str = None, matching: str = 'like') -> List[tuple]: ...
509
    def locations_for(self, city_name: str, country: str = None, state: str = None, matching: str = 'like') -> List[Location]: ...
510
```