0
# Hourly Weather Data
1

2
The Hourly class provides access to hourly meteorological observations including temperature, humidity, precipitation, wind conditions, pressure, and weather codes. It supports timezone localization and includes both observational and model data sources.
3

4
## Capabilities
5

6
### Hourly Data Initialization
7

8
Create an hourly time series for weather stations or geographic points with flexible time range and data source options.
9

10
```python { .api }
11
class Hourly:
12
    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:
13
        """
14
        Initialize hourly weather data retrieval.
15
        
16
        Parameters:
17
        - loc: Union[pd.DataFrame, Point, list, str]
18
            - pd.DataFrame: Station data from Stations.fetch()
19
            - Point: Geographic point for automatic station selection
20
            - list: List of station IDs  
21
            - str: Single station ID
22
        - start: datetime, start of time period (default: 1890-01-01)
23
        - end: datetime, end of time period (default: 10 days from today)
24
        - timezone: str, optional IANA timezone name for localization
25
        - model: bool, whether to include model/forecast data (default: True)
26
        - flags: bool, whether to include data source flags (default: False)
27
        """
28
```
29

30
### Row Count Estimation
31

32
Calculate expected number of hourly observations for the defined time period.
33

34
```python { .api }
35
def expected_rows(self) -> int:
36
    """
37
    Return expected number of hourly rows for the date range.
38
    
39
    Returns:
40
    int, expected number of hourly observations
41
    """
42
```
43

44
## Data Columns
45

46
Hourly data includes the following meteorological parameters:
47

48
```python { .api }
49
# Temperature measurements (°C)
50
temp: float       # Air temperature 
51
dwpt: float       # Dew point temperature
52

53
# Humidity and precipitation
54
rhum: float       # Relative humidity (%)
55
prcp: float       # Precipitation amount (mm)
56

57
# Snow and winter weather  
58
snow: float       # Snow depth (mm)
59

60
# Wind measurements
61
wdir: float       # Wind direction (degrees, 0-360)
62
wspd: float       # Wind speed (km/h)
63
wpgt: float       # Wind gust speed (km/h)
64

65
# Atmospheric pressure
66
pres: float       # Sea level pressure (hPa)
67

68
# Solar and weather conditions
69
tsun: float       # Sunshine duration (minutes)
70
coco: float       # Weather condition code (1-27)
71

72
# Data quality flags (when flags=True)
73
temp_flag: str    # Temperature data source flag
74
dwpt_flag: str    # Dew point data source flag
75
# ... (additional _flag columns for each parameter)
76
```
77

78
## Usage Examples
79

80
### Basic Hourly Data Retrieval
81

82
```python
83
from datetime import datetime
84
from meteostat import Point, Hourly
85

86
# Set time period
87
start = datetime(2020, 1, 1)
88
end = datetime(2020, 1, 31)
89

90
# Create point for Vancouver, BC
91
vancouver = Point(49.2497, -123.1193, 70)
92

93
# Get hourly data
94
data = Hourly(vancouver, start, end)
95
hourly_data = data.fetch()
96

97
print(f"Retrieved {len(hourly_data)} hourly observations")
98
print(hourly_data[['temp', 'rhum', 'prcp', 'wspd']].head())
99
```
100

101
### Station-Based Hourly Data
102

103
```python
104
from datetime import datetime
105
from meteostat import Stations, Hourly
106

107
# Select stations in New York area
108
stations = Stations().nearby(40.7128, -74.0060, 50000).fetch(5)
109

110
# Get hourly data for multiple stations
111
start = datetime(2020, 6, 1)
112
end = datetime(2020, 6, 7)
113

114
data = Hourly(stations, start, end)
115
hourly_data = data.fetch()
116

117
# Data includes station column for multi-station queries
118
print(hourly_data.groupby('station')['temp'].mean())
119
```
120

121
### Timezone Localization
122

123
```python
124
from datetime import datetime
125
from meteostat import Point, Hourly
126

127
# Create point for Tokyo
128
tokyo = Point(35.6762, 139.6503)
129

130
# Get hourly data with Tokyo timezone
131
start = datetime(2020, 7, 1, 0, 0, 0)
132
end = datetime(2020, 7, 1, 23, 59, 59)
133

134
data = Hourly(tokyo, start, end, timezone='Asia/Tokyo')
135
hourly_data = data.fetch()
136

137
print("Hourly temperatures in Tokyo (JST):")
138
print(hourly_data[['temp']].head(10))
139
```
140

141
### Including Data Source Flags
142

143
```python
144
from datetime import datetime
145
from meteostat import Point, Hourly
146

147
# Get hourly data with source quality flags
148
location = Point(52.5200, 13.4050)  # Berlin
149
start = datetime(2020, 12, 1)  
150
end = datetime(2020, 12, 7)
151

152
data = Hourly(location, start, end, flags=True)
153
hourly_data = data.fetch()
154

155
# Examine data sources
156
print("Data source flags:")
157
print(hourly_data[['temp', 'temp_flag', 'prcp', 'prcp_flag']].head())
158
```
159

160
### Excluding Model Data
161

162
```python
163
from datetime import datetime
164
from meteostat import Point, Hourly
165

166
# Get only observational data (no model/forecast data)
167
location = Point(41.8781, -87.6298)  # Chicago
168
start = datetime(2019, 1, 1)
169
end = datetime(2019, 1, 31)
170

171
data = Hourly(location, start, end, model=False)
172
observational_data = data.fetch()
173

174
print(f"Observational data points: {len(observational_data)}")
175
```
176

177
## Data Source Flags
178

179
When `flags=True`, each meteorological parameter includes a corresponding source flag indicating data origin:
180

181
```python { .api }
182
# Source flag meanings
183
"A": str  # High-quality government weather service data
184
"B": str  # ISD Lite observational data  
185
"C": str  # SYNOP observational data
186
"D": str  # METAR aviation weather reports
187
"E": str  # Model/forecast data (reanalysis, numerical weather prediction)
188
```
189

190
## Weather Condition Codes
191

192
The `coco` parameter uses Meteostat's standardized condition codes:
193

194
```python { .api }
195
# Condition code ranges
196
1-4:   Clear to overcast conditions
197
5-6:   Fog conditions  
198
7-13:  Rain and freezing rain
199
14-16: Snow conditions
200
17-22: Shower conditions
201
23-27: Thunderstorm and severe weather
202
```
203

204
Use the `units.condition()` function to convert codes to descriptive strings:
205

206
```python
207
from meteostat import units
208

209
# Convert condition code to description
210
condition_desc = hourly_data['coco'].apply(units.condition)
211
print(condition_desc.value_counts())
212
```
213

214
## Time Series Processing
215

216
Hourly data objects inherit all time series processing methods:
217

218
```python { .api }
219
# Data retrieval and analysis
220
def fetch(self) -> pd.DataFrame: ...
221
def count(self) -> int: ...
222
def coverage(self): ...
223

224
# Data processing
225
def normalize(self): ...
226
def interpolate(self, limit: int = 3): ...
227
def aggregate(self, freq: str, spatial: bool = False): ...
228
def convert(self, units: dict): ...
229

230
# Utility methods
231
def stations(self) -> pd.Index: ...
232
def clear_cache(self): ...
233
```