0
# Weather API
1

2
Current weather conditions, forecasts, and historical weather data from OpenWeatherMap's Weather API v2.5 and OneCall API. Supports location queries by name, coordinates, city ID, zip code, and provides comprehensive weather forecasting capabilities.
3

4
## Capabilities
5

6
### Current Weather Data
7

8
Retrieve current weather observations for any location worldwide using various location identifiers.
9

10
```python { .api }
11
class WeatherManager:
12
    def weather_api_version(self) -> tuple:
13
        """
14
        Get Weather API version.
15
        
16
        Returns:
17
        Tuple representing the API version
18
        """
19
    
20
    def weather_at_place(self, name: str) -> Observation:
21
        """
22
        Get current weather by location name.
23
        
24
        Parameters:
25
        - name: Location name (e.g., 'London,GB', 'New York,US')
26
        
27
        Returns:
28
        Observation object containing current weather data
29
        """
30
    
31
    def weather_at_coords(self, lat: float, lon: float) -> Observation:
32
        """
33
        Get current weather by geographic coordinates.
34
        
35
        Parameters:
36
        - lat: Latitude (-90.0 to 90.0)
37
        - lon: Longitude (-180.0 to 180.0)
38
        
39
        Returns:
40
        Observation object containing current weather data
41
        """
42
    
43
    def weather_at_zip_code(self, zipcode: str, country: str) -> Observation:
44
        """
45
        Get current weather by postal/zip code.
46
        
47
        Parameters:
48
        - zipcode: Postal/zip code
49
        - country: Two-letter country code (ISO 3166)
50
        
51
        Returns:
52
        Observation object containing current weather data
53
        """
54
    
55
    def weather_at_id(self, id: int) -> Observation:
56
        """
57
        Get current weather by OpenWeatherMap city ID.
58
        
59
        Parameters:
60
        - id: OpenWeatherMap city ID
61
        
62
        Returns:
63
        Observation object containing current weather data
64
        """
65
    
66
    def weather_at_ids(self, ids_list: List[int]) -> List[Observation]:
67
        """
68
        Get current weather for multiple city IDs.
69
        
70
        Parameters:
71
        - ids_list: List of OpenWeatherMap city IDs
72
        
73
        Returns:
74
        List of Observation objects
75
        """
76
```
77

78
### Location-Based Weather Searches
79

80
Search for weather data across multiple locations using patterns and geographic areas.
81

82
```python { .api }
83
class WeatherManager:
84
    def weather_at_places(self, pattern: str, searchtype: str, limit: int = None) -> List[Observation]:
85
        """
86
        Search weather by location pattern.
87
        
88
        Parameters:
89
        - pattern: Location search pattern
90
        - searchtype: 'accurate' for exact matches, 'like' for partial matches
91
        - limit: Maximum number of results (optional)
92
        
93
        Returns:
94
        List of Observation objects matching the search
95
        """
96
    
97
    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]:
98
        """
99
        Get weather data within a bounding box.
100
        
101
        Parameters:
102
        - lon_left: Left longitude boundary
103
        - lat_bottom: Bottom latitude boundary  
104
        - lon_right: Right longitude boundary
105
        - lat_top: Top latitude boundary
106
        - zoom: Map zoom level (1-20)
107
        - cluster: Whether to cluster nearby stations
108
        
109
        Returns:
110
        List of Observation objects within the bounding box
111
        """
112
    
113
    def weather_around_coords(self, lat: float, lon: float, limit: int = None) -> List[Observation]:
114
        """
115
        Get weather data around coordinates.
116
        
117
        Parameters:
118
        - lat: Center latitude
119
        - lon: Center longitude
120
        - limit: Maximum number of results (optional)
121
        
122
        Returns:
123
        List of Observation objects around the coordinates
124
        """
125
```
126

127
### Weather Forecasts
128

129
Retrieve weather forecast data with different time granularities and forecast horizons.
130

131
```python { .api }
132
class WeatherManager:
133
    def forecast_at_place(self, name: str, interval: str, limit: int = None) -> Forecaster:
134
        """
135
        Get weather forecast by location name.
136
        
137
        Parameters:
138
        - name: Location name (e.g., 'London,GB')
139
        - interval: '3h' for 3-hourly or 'daily' for daily forecasts
140
        - limit: Maximum number of forecast items (optional)
141
        
142
        Returns:
143
        Forecaster object with forecast manipulation methods
144
        """
145
    
146
    def forecast_at_coords(self, lat: float, lon: float, interval: str, limit: int = None) -> Forecaster:
147
        """
148
        Get weather forecast by coordinates.
149
        
150
        Parameters:
151
        - lat: Latitude (-90.0 to 90.0)
152
        - lon: Longitude (-180.0 to 180.0)
153
        - interval: '3h' for 3-hourly or 'daily' for daily forecasts
154
        - limit: Maximum number of forecast items (optional)
155
        
156
        Returns:
157
        Forecaster object with forecast manipulation methods
158
        """
159
    
160
    def forecast_at_id(self, id: int, interval: str, limit: int = None) -> Forecaster:
161
        """
162
        Get weather forecast by city ID.
163
        
164
        Parameters:
165
        - id: OpenWeatherMap city ID
166
        - interval: '3h' for 3-hourly or 'daily' for daily forecasts
167
        - limit: Maximum number of forecast items (optional)
168
        
169
        Returns:
170
        Forecaster object with forecast manipulation methods
171
        """
172
```
173

174
### OneCall API
175

176
Comprehensive weather data in a single API call including current weather, forecasts, alerts, and historical data.
177

178
```python { .api }
179
class WeatherManager:
180
    def one_call(self, lat: Union[int, float], lon: Union[int, float], **kwargs) -> OneCall:
181
        """
182
        Get comprehensive weather data via OneCall API.
183
        
184
        Parameters:
185
        - lat: Latitude
186
        - lon: Longitude
187
        - exclude: List of data parts to exclude ('current', 'minutely', 'hourly', 'daily', 'alerts')
188
        - units: Units format ('standard', 'metric', 'imperial')
189
        - lang: Language code for weather descriptions
190
        
191
        Returns:
192
        OneCall object with current weather, forecasts, and alerts
193
        """
194
    
195
    def one_call_history(self, lat: Union[int, float], lon: Union[int, float], dt: int = None) -> OneCall:
196
        """
197
        Get historical weather data via OneCall API.
198
        
199
        Parameters:
200
        - lat: Latitude
201
        - lon: Longitude
202
        - dt: UNIX timestamp for historical data (optional, defaults to yesterday)
203
        
204
        Returns:
205
        OneCall object with historical weather data
206
        """
207
```
208

209
### Station Weather History
210

211
Historical weather data from weather stations with different time aggregations.
212

213
```python { .api }
214
class WeatherManager:
215
    def station_tick_history(self, station_ID: int, limit: int = None) -> Historian:
216
        """
217
        Get minute-level weather station history.
218
        
219
        Parameters:
220
        - station_ID: Weather station ID
221
        - limit: Maximum number of measurements (optional)
222
        
223
        Returns:
224
        Historian object with historical data analysis methods
225
        """
226
    
227
    def station_hour_history(self, station_ID: int, limit: int = None) -> Historian:
228
        """
229
        Get hourly weather station history.
230
        
231
        Parameters:
232
        - station_ID: Weather station ID
233
        - limit: Maximum number of measurements (optional)
234
        
235
        Returns:
236
        Historian object with historical data analysis methods
237
        """
238
    
239
    def station_day_history(self, station_ID: int, limit: int = None) -> Historian:
240
        """
241
        Get daily weather station history.
242
        
243
        Parameters:
244
        - station_ID: Weather station ID
245
        - limit: Maximum number of measurements (optional)
246
        
247
        Returns:
248
        Historian object with historical data analysis methods
249
        """
250
```
251

252
## Usage Examples
253

254
### Basic Weather Data
255

256
```python
257
from pyowm import OWM
258

259
owm = OWM('your-api-key')
260
mgr = owm.weather_manager()
261

262
# Current weather by location name
263
observation = mgr.weather_at_place('London,GB')
264
weather = observation.weather
265

266
print(f"Temperature: {weather.temperature('celsius')['temp']}°C")
267
print(f"Feels like: {weather.temperature('celsius')['feels_like']}°C")
268
print(f"Status: {weather.detailed_status}")
269
print(f"Humidity: {weather.humidity}%")
270
print(f"Pressure: {weather.barometric_pressure()['press']} hPa")
271
print(f"Wind: {weather.wind()['speed']} m/s")
272

273
# Weather by coordinates
274
observation = mgr.weather_at_coords(51.5074, -0.1278)
275
weather = observation.weather
276
print(f"London weather: {weather.status}")
277
```
278

279
### Weather Forecasts
280

281
```python
282
# 3-hourly forecast
283
forecaster = mgr.forecast_at_place('New York,US', '3h')
284

285
# Check if it will rain in the forecast period
286
if forecaster.will_have_rain():
287
    print("Rain is expected!")
288
    rainy_times = forecaster.when_rain()
289
    for weather in rainy_times:
290
        print(f"Rain at: {weather.reference_time('iso')}")
291

292
# Get extreme weather conditions
293
hottest = forecaster.most_hot()
294
coldest = forecaster.most_cold()
295
windiest = forecaster.most_windy()
296

297
print(f"Hottest: {hottest.temperature('celsius')['temp']}°C")
298
print(f"Coldest: {coldest.temperature('celsius')['temp']}°C")
299
print(f"Windiest: {windiest.wind()['speed']} m/s")
300

301
# Daily forecast
302
daily_forecaster = mgr.forecast_at_place('Tokyo,JP', 'daily')
303
forecast = daily_forecaster.forecast
304

305
for weather in forecast[:5]:  # Next 5 days
306
    temp = weather.temperature('celsius')
307
    print(f"{weather.reference_time('iso')}: {temp['min']}-{temp['max']}°C, {weather.status}")
308
```
309

310
### OneCall API Usage
311

312
```python
313
# Comprehensive weather data
314
one_call = mgr.one_call(lat=40.7128, lon=-74.0060, exclude=['minutely'])
315

316
# Current weather
317
current = one_call.current
318
print(f"Current: {current.temperature('celsius')['temp']}°C, {current.status}")
319

320
# Hourly forecast (next 48 hours)
321
if one_call.forecast_hourly:
322
    for weather in one_call.forecast_hourly[:12]:  # Next 12 hours
323
        temp = weather.temperature('celsius')['temp']
324
        print(f"{weather.reference_time('iso')}: {temp}°C")
325

326
# Daily forecast (next 8 days)
327
if one_call.forecast_daily:
328
    for weather in one_call.forecast_daily:
329
        temp = weather.temperature('celsius')
330
        print(f"{weather.reference_time('iso')}: {temp['min']}-{temp['max']}°C")
331

332
# Weather alerts
333
if one_call.national_weather_alerts:
334
    for alert in one_call.national_weather_alerts:
335
        print(f"Alert: {alert.title}")
336
        print(f"Description: {alert.description}")
337
        print(f"Start: {alert.start_time('iso')}")
338
        print(f"End: {alert.end_time('iso')}")
339
```
340

341
## Data Types
342

343
```python { .api }
344
class Observation:
345
    def __init__(self, reception_time: int, location: Location, weather: Weather): ...
346
    
347
    def reception_time(self, timeformat: str = 'unix') -> Union[int, str, datetime]: ...
348
    
349
    @property
350
    def location(self) -> Location: ...
351
    @property
352
    def weather(self) -> Weather: ...
353
    
354
    def to_dict(self) -> dict: ...
355

356
class Weather:
357
    def reference_time(self, timeformat: str = 'unix') -> Union[int, str, datetime]: ...
358
    def sunset_time(self, timeformat: str = 'unix') -> Union[int, str, datetime, None]: ...
359
    def sunrise_time(self, timeformat: str = 'unix') -> Union[int, str, datetime, None]: ...
360
    def wind(self, unit: str = 'meters_sec') -> dict: ...
361
    def temperature(self, unit: str = 'kelvin') -> dict: ...
362
    def barometric_pressure(self, unit: str = 'hPa') -> dict: ...
363
    def visibility(self, unit: str = 'meters') -> float: ...
364
    def weather_icon_url(self, size: str = "") -> str: ...
365
    
366
    @property
367
    def status(self) -> str: ...
368
    @property
369
    def detailed_status(self) -> str: ...
370
    @property
371
    def weather_code(self) -> int: ...
372
    @property
373
    def weather_icon_name(self) -> str: ...
374
    @property
375
    def clouds(self) -> int: ...
376
    @property
377
    def rain(self) -> dict: ...
378
    @property
379
    def snow(self) -> dict: ...
380
    @property
381
    def humidity(self) -> int: ...
382
    @property
383
    def dewpoint(self) -> float: ...
384
    @property
385
    def heat_index(self) -> float: ...
386
    @property
387
    def humidex(self) -> float: ...
388
    @property
389
    def visibility_distance(self) -> float: ...
390
    @property
391
    def uvi(self) -> Union[int, float, None]: ...
392
    @property
393
    def precipitation_probability(self) -> Union[float, None]: ...
394
    
395
    def to_dict(self) -> dict: ...
396

397
class Forecast:
398
    def __init__(self, interval: str, reception_time: int, location: Location, weathers: List[Weather]): ...
399
    
400
    def get(self, index: int) -> Weather: ...
401
    def reception_time(self, timeformat: str = 'unix') -> Union[int, str, datetime]: ...
402
    def actualize(self) -> None: ...
403
    
404
    @property
405
    def interval(self) -> str: ...
406
    @property
407
    def location(self) -> Location: ...
408
    @property
409
    def weathers(self) -> List[Weather]: ...
410
    
411
    def __len__(self) -> int: ...
412
    def __iter__(self): ...
413

414
class Forecaster:
415
    def __init__(self, forecast: Forecast): ...
416
    
417
    def when_starts(self, timeformat: str = 'unix') -> Union[int, str, datetime]: ...
418
    def when_ends(self, timeformat: str = 'unix') -> Union[int, str, datetime]: ...
419
    
420
    # Weather condition checks
421
    def will_have_rain(self) -> bool: ...
422
    def will_have_clear(self) -> bool: ...
423
    def will_have_fog(self) -> bool: ...
424
    def will_have_clouds(self) -> bool: ...
425
    def will_have_snow(self) -> bool: ...
426
    def will_have_storm(self) -> bool: ...
427
    def will_have_tornado(self) -> bool: ...
428
    def will_have_hurricane(self) -> bool: ...
429
    
430
    # Weather filtering
431
    def when_rain(self) -> List[Weather]: ...
432
    def when_clear(self) -> List[Weather]: ...
433
    def when_fog(self) -> List[Weather]: ...
434
    def when_clouds(self) -> List[Weather]: ...
435
    def when_snow(self) -> List[Weather]: ...
436
    def when_storm(self) -> List[Weather]: ...
437
    def when_tornado(self) -> List[Weather]: ...
438
    def when_hurricane(self) -> List[Weather]: ...
439
    
440
    # Time-specific weather checks
441
    def will_be_rainy_at(self, timeobject) -> bool: ...
442
    def will_be_clear_at(self, timeobject) -> bool: ...
443
    def will_be_snowy_at(self, timeobject) -> bool: ...
444
    def will_be_cloudy_at(self, timeobject) -> bool: ...
445
    def will_be_foggy_at(self, timeobject) -> bool: ...
446
    def will_be_stormy_at(self, timeobject) -> bool: ...
447
    def will_be_tornado_at(self, timeobject) -> bool: ...
448
    def will_be_hurricane_at(self, timeobject) -> bool: ...
449
    
450
    def get_weather_at(self, timeobject) -> Weather: ...
451
    
452
    # Weather extremes
453
    def most_hot(self) -> Union[Weather, None]: ...
454
    def most_cold(self) -> Union[Weather, None]: ...
455
    def most_humid(self) -> Union[Weather, None]: ...
456
    def most_rainy(self) -> Union[Weather, None]: ...
457
    def most_snowy(self) -> Union[Weather, None]: ...
458
    def most_windy(self) -> Union[Weather, None]: ...
459
    
460
    @property
461
    def forecast(self) -> Forecast: ...
462

463
class OneCall:
464
    def __init__(self, lat: Union[int, float], lon: Union[int, float], timezone: str, 
465
                 current: Weather, forecast_minutely: Optional[List[Weather]] = None,
466
                 forecast_hourly: Optional[List[Weather]] = None, 
467
                 forecast_daily: Optional[List[Weather]] = None,
468
                 national_weather_alerts: Optional[List] = None): ...
469
    
470
    def to_geopoint(self) -> Point: ...
471
    
472
    @property
473
    def lat(self) -> Union[int, float]: ...
474
    @property
475
    def lon(self) -> Union[int, float]: ...
476
    @property
477
    def timezone(self) -> str: ...
478
    @property
479
    def current(self) -> Weather: ...
480
    @property
481
    def forecast_minutely(self) -> Optional[List[Weather]]: ...
482
    @property
483
    def forecast_hourly(self) -> Optional[List[Weather]]: ...
484
    @property
485
    def forecast_daily(self) -> Optional[List[Weather]]: ...
486
    @property
487
    def national_weather_alerts(self) -> Optional[List]: ...
488

489
class Historian:
490
    def __init__(self, station_history): ...
491
    
492
    # Time series data
493
    def temperature_series(self, unit: str = 'kelvin') -> List[Tuple[int, float]]: ...
494
    def humidity_series(self) -> List[Tuple[int, int]]: ...
495
    def pressure_series(self) -> List[Tuple[int, float]]: ...
496
    def rain_series(self) -> List[Tuple[int, float]]: ...
497
    def wind_series(self) -> List[Tuple[int, dict]]: ...
498
    
499
    # Statistical methods
500
    def max_temperature(self, unit: str = 'kelvin') -> Tuple[int, float]: ...
501
    def min_temperature(self, unit: str = 'kelvin') -> Tuple[int, float]: ...
502
    def average_temperature(self, unit: str = 'kelvin') -> float: ...
503
    def max_humidity(self) -> Tuple[int, int]: ...
504
    def min_humidity(self) -> Tuple[int, int]: ...
505
    def average_humidity(self) -> float: ...
506
    def max_pressure(self) -> Tuple[int, float]: ...
507
    def min_pressure(self) -> Tuple[int, float]: ...
508
    def average_pressure(self) -> float: ...
509
    def max_rain(self) -> Tuple[int, float]: ...
510
    def min_rain(self) -> Tuple[int, float]: ...
511
    def average_rain(self) -> float: ...
512

513
class NationalWeatherAlert:
514
    def __init__(self, sender: str, title: str, description: str, start_time: int, end_time: int, tags: Optional[List[str]] = None): ...
515
    
516
    def start_time(self, timeformat: str = 'unix') -> Union[int, str, datetime]: ...
517
    def end_time(self, timeformat: str = 'unix') -> Union[int, str, datetime]: ...
518
    
519
    @property
520
    def sender(self) -> str: ...
521
    @property
522
    def title(self) -> str: ...
523
    @property
524
    def description(self) -> str: ...
525
    @property
526
    def tags(self) -> Optional[List[str]]: ...
527
    
528
    def to_dict(self) -> dict: ...
529
```