0
# Meteostat
1

2
A comprehensive Python library for accessing and analyzing historical weather and climate data through a simple, intuitive API. Meteostat enables developers and researchers to fetch meteorological observations and statistics from various governmental sources including NOAA and DWD, offering access to weather station data, geographical point-based data, and time series information at hourly, daily, and monthly granularity.
3

4
## Package Information
5

6
- **Package Name**: meteostat
7
- **Language**: Python
8
- **Installation**: `pip install meteostat`
9
- **Requirements**: Python 3.6+
10

11
## Core Imports
12

13
```python
14
import meteostat
15
```
16

17
Common imports for working with weather data:
18

19
```python
20
from meteostat import Stations, Point, Hourly, Daily, Monthly, Normals
21
```
22

23
For unit conversions:
24

25
```python
26
from meteostat import units
27
```
28

29
For enumerations and type annotations:
30

31
```python
32
from meteostat.enumerations.granularity import Granularity
33
from typing import Union, Optional
34
from datetime import datetime
35
```
36

37
## Basic Usage
38

39
```python
40
from datetime import datetime
41
from meteostat import Point, Daily
42

43
# Set time period
44
start = datetime(2018, 1, 1)
45
end = datetime(2018, 12, 31)
46

47
# Create Point for Vancouver, BC
48
location = Point(49.2497, -123.1193, 70)
49

50
# Get daily data
51
data = Daily(location, start, end)
52
data = data.fetch()
53

54
# Print daily average temperature
55
print(data['tavg'])
56
```
57

58
## Architecture
59

60
Meteostat follows a modular design centered on location selection and time series data retrieval:
61

62
- **Location Selection**: Choose weather stations (`Stations`) or geographic points (`Point`)
63
- **Time Series Classes**: Retrieve data at different temporal granularities (`Hourly`, `Daily`, `Monthly`)
64
- **Climate Data**: Access long-term averages through climate normals (`Normals`)
65
- **Data Processing**: Built-in methods for aggregation, interpolation, and unit conversion
66
- **Caching System**: Efficient local caching with configurable retention and cleanup
67

68
This design enables seamless integration with pandas DataFrames for data manipulation and matplotlib for visualization, making it ideal for meteorological research, climate analysis, and weather applications.
69

70
## Configuration
71

72
Global configuration options that can be modified on the Base class to customize behavior across all meteostat operations.
73

74
```python { .api }
75
class Base:
76
    endpoint: str = "https://bulk.meteostat.net/v2/"
77
    proxy: Optional[str] = None
78
    cache_dir: str = "~/.meteostat/cache"
79
    autoclean: bool = True
80
    max_age: int = 86400  # 24 hours in seconds
81
    processes: int = 1
82
    threads: int = 1
83
```
84

85
Example configuration:
86

87
```python
88
from meteostat import Base
89

90
# Set up proxy for network requests
91
Base.proxy = "http://proxy.company.com:8080"
92

93
# Change cache location
94
Base.cache_dir = "/tmp/meteostat_cache"
95

96
# Increase cache retention to 1 week
97
Base.max_age = 7 * 24 * 60 * 60
98
```
99

100
## Capabilities
101

102
### Weather Station Selection
103

104
Select and filter weather stations from the global network based on location, country, geographical bounds, and data availability. Stations can be sorted by distance and filtered by data inventory.
105

106
```python { .api }
107
class Stations:
108
    def __init__(self) -> None: ...
109
    def nearby(self, lat: float, lon: float, radius: int = None) -> "Stations": ...
110
    def region(self, country: str, state: str = None) -> "Stations": ...
111
    def bounds(self, top_left: tuple, bottom_right: tuple) -> "Stations": ...
112
    def inventory(self, freq: str, required: Union[datetime, tuple, bool] = True) -> "Stations": ...
113
```
114

115
[Weather Stations](./weather-stations.md)
116

117
### Geographic Point Data
118

119
Automatically select and interpolate data from nearby weather stations for any geographic location. Uses intelligent station selection and weighting algorithms for optimal data quality.
120

121
```python { .api }
122
class Point:
123
    def __init__(self, lat: float, lon: float, alt: int = None) -> None: ...
124
    def get_stations(self, freq: str = None, start: datetime = None, end: datetime = None, model: bool = True) -> pd.DataFrame: ...
125
```
126

127
[Geographic Points](./geographic-points.md)
128

129
### Hourly Weather Data
130

131
Retrieve hourly meteorological observations including temperature, humidity, precipitation, wind, pressure, and weather conditions. Supports timezone localization and model data inclusion.
132

133
```python { .api }
134
class Hourly:
135
    def __init__(self, loc: Union[pd.DataFrame, Point, list, str], start=datetime(1890, 1, 1, 0, 0, 0), end=datetime.combine(datetime.today().date() + timedelta(days=10), datetime.max.time()), timezone: Optional[str] = None, model=True, flags=False) -> None: ...
136
    def expected_rows(self) -> int: ...
137
```
138

139
[Hourly Data](./hourly-data.md)
140

141
### Daily Weather Data
142

143
Access daily weather summaries with temperature extremes, precipitation totals, wind averages, and sunshine duration. Historical data available from 1781 for some locations.
144

145
```python { .api }
146
class Daily:
147
    def __init__(self, loc: Union[pd.DataFrame, Point, list, str], start=datetime(1781, 1, 1, 0, 0, 0), end=datetime.combine(datetime.today().date() + timedelta(days=10), datetime.max.time()), model=True, flags=False) -> None: ...
148
    def expected_rows(self) -> int: ...
149
```
150

151
[Daily Data](./daily-data.md)
152

153
### Monthly Weather Data
154

155
Monthly aggregated weather statistics providing long-term climate patterns and trends. Ideal for climate analysis and seasonal comparisons.
156

157
```python { .api }
158
class Monthly:
159
    def __init__(self, loc: Union[pd.DataFrame, Point, list, str], start: datetime = None, end: datetime = None, model: bool = True, flags: bool = False) -> None: ...
160
    def expected_rows(self) -> int: ...
161
```
162

163
[Monthly Data](./monthly-data.md)
164

165
### Climate Normals
166

167
Climate normals providing 30-year averages for temperature, precipitation, and other parameters. Essential for climate research and establishing baseline conditions.
168

169
```python { .api }
170
class Normals:
171
    def __init__(self, loc: Union[pd.DataFrame, Point, list, str], start: int = None, end: int = None) -> None: ...
172
    def normalize(self): ...
173
```
174

175
[Climate Normals](./climate-normals.md)
176

177
### Data Processing and Analysis
178

179
Built-in methods for time series analysis including normalization, interpolation, aggregation, unit conversion, and data quality assessment.
180

181
```python { .api }
182
# Available on all time series classes
183
def fetch(self) -> pd.DataFrame: ...
184
def normalize(self): ...
185
def interpolate(self, limit: int = 3): ...
186
def aggregate(self, freq: str, spatial: bool = False): ...
187
def convert(self, units: dict): ...
188
def coverage(self): ...
189
def count(self) -> int: ...
190
```
191

192
[Data Processing](./data-processing.md)
193

194
### Unit Conversions
195

196
Comprehensive unit conversion functions for temperature, precipitation, wind speed, pressure, and other meteorological parameters.
197

198
```python { .api }
199
def fahrenheit(value): ...
200
def kelvin(value): ...
201
def inches(value): ...
202
def mph(value): ...
203
def direction(value): ...
204
def condition(value): ...
205

206
imperial: dict
207
scientific: dict
208
```
209

210
[Unit Conversions](./unit-conversions.md)
211

212
## Types
213

214
```python { .api }
215
from typing import Union, Optional
216
from datetime import datetime
217
import pandas as pd
218

219
# Location types
220
LocationType = Union[pd.DataFrame, Point, list, str]
221

222
# Granularity enumeration
223
class Granularity(Enum):
224
    HOURLY = "hourly"
225
    DAILY = "daily"
226
    MONTHLY = "monthly"
227
    NORMALS = "normals"
228
```