0
# Weather Station Selection
1

2
The Stations class provides comprehensive functionality for selecting and filtering weather stations from the global Meteostat network. It enables location-based queries, regional filtering, inventory checks, and distance-based sorting.
3

4
## Capabilities
5

6
### Station Initialization
7

8
Load the complete database of weather stations worldwide. The constructor automatically fetches and caches the station list.
9

10
```python { .api }
11
class Stations:
12
    def __init__(self) -> None:
13
        """
14
        Initialize with all available weather stations.
15
        Automatically loads and caches the global station database.
16
        """
17
```
18

19
### Distance-Based Selection
20

21
Find weather stations near a specific geographic location, optionally filtered by maximum distance radius.
22

23
```python { .api }
24
def nearby(self, lat: float, lon: float, radius: int = None) -> "Stations":
25
    """
26
    Filter and sort stations by distance from coordinates.
27
    
28
    Parameters:
29
    - lat: float, latitude in decimal degrees
30
    - lon: float, longitude in decimal degrees  
31
    - radius: int, optional maximum distance in meters
32
    
33
    Returns:
34
    Stations object with filtered and distance-sorted stations
35
    """
36
```
37

38
### Regional Filtering
39

40
Filter stations by country and optionally by state/region using ISO country codes and regional identifiers.
41

42
```python { .api }
43
def region(self, country: str, state: str = None) -> "Stations":
44
    """
45
    Filter stations by country and optional state/region.
46
    
47
    Parameters:
48
    - country: str, ISO country code (e.g., 'US', 'CA', 'DE')
49
    - state: str, optional state/region code
50
    
51
    Returns:
52
    Stations object filtered by geographic region
53
    """
54
```
55

56
### Geographical Bounds
57

58
Select stations within rectangular geographical boundaries defined by top-left and bottom-right coordinates.
59

60
```python { .api }
61
def bounds(self, top_left: tuple, bottom_right: tuple) -> "Stations":
62
    """
63
    Filter stations within geographical boundaries.
64
    
65
    Parameters:
66
    - top_left: tuple, (latitude, longitude) of northwest corner
67
    - bottom_right: tuple, (latitude, longitude) of southeast corner
68
    
69
    Returns:
70
    Stations object with stations within specified bounds
71
    """
72
```
73

74
### Data Inventory Filtering
75

76
Filter stations based on data availability for specific time periods and measurement frequencies.
77

78
```python { .api }
79
def inventory(self, freq: str, required: Union[datetime, tuple, bool] = True) -> "Stations":
80
    """
81
    Filter stations by data inventory availability.
82
    
83
    Parameters:
84
    - freq: str, data frequency ('hourly', 'daily', 'monthly')
85
    - required: Union[datetime, tuple, bool]
86
        - True: require any data at specified frequency
87
        - datetime: require data on specific date
88
        - tuple: require data across entire period (start, end)
89
    
90
    Returns:
91
    Stations object with stations having required data availability
92
    """
93
```
94

95
### Unit Conversion
96

97
Apply unit conversions to station metadata (elevation, coordinates).
98

99
```python { .api }
100
def convert(self, units: dict) -> "Stations":
101
    """
102
    Convert station metadata to different units.
103
    
104
    Parameters:
105
    - units: dict, mapping of column names to conversion functions
106
        e.g., {'elevation': units.feet, 'distance': units.feet}
107
    
108
    Returns:
109
    Stations object with converted units
110
    """
111
```
112

113
### Data Retrieval
114

115
Access the filtered station data as pandas DataFrames with optional sampling and limiting.
116

117
```python { .api }
118
def count(self) -> int:
119
    """
120
    Return number of stations in current selection.
121
    
122
    Returns:
123
    int, count of selected stations
124
    """
125

126
def fetch(self, limit: int = None, sample: bool = False) -> pd.DataFrame:
127
    """
128
    Fetch station data as DataFrame.
129
    
130
    Parameters:
131
    - limit: int, optional maximum number of stations to return
132
    - sample: bool, whether to randomly sample when limiting
133
    
134
    Returns:
135
    pandas.DataFrame with station metadata and availability information
136
    """
137

138
def clear_cache(self):
139
    """Clear cached station data files."""
140
```
141

142
## Usage Examples
143

144
### Find Nearby Stations
145

146
```python
147
from meteostat import Stations
148

149
# Get stations within 50km of New York City
150
stations = Stations()
151
stations = stations.nearby(40.7128, -74.0060, 50000)
152

153
# Get the 10 closest stations
154
nearby_stations = stations.fetch(10)
155
print(nearby_stations[['name', 'distance', 'elevation']])
156
```
157

158
### Regional Station Selection
159

160
```python
161
# Get all stations in Germany
162
german_stations = Stations().region('DE')
163

164
# Get stations in California, USA
165
ca_stations = Stations().region('US', 'CA')
166

167
print(f"German stations: {german_stations.count()}")
168
print(f"California stations: {ca_stations.count()}")
169
```
170

171
### Inventory-Based Selection
172

173
```python
174
from datetime import datetime
175

176
# Find stations with daily data for 2020
177
start = datetime(2020, 1, 1)
178
end = datetime(2020, 12, 31)
179

180
stations_with_data = Stations().nearby(51.5074, -0.1278).inventory('daily', (start, end))
181
print(f"Stations with 2020 daily data: {stations_with_data.count()}")
182
```
183

184
## Station Data Columns
185

186
The DataFrame returned by `fetch()` contains the following columns:
187

188
```python { .api }
189
# Station identification
190
id: str           # Unique station identifier
191
name: str         # Station name
192
wmo: str          # WMO station ID (if available)
193
icao: str         # ICAO station code (if available)
194

195
# Geographic information  
196
latitude: float   # Latitude in decimal degrees
197
longitude: float  # Longitude in decimal degrees
198
elevation: float  # Elevation in meters above sea level
199
timezone: str     # IANA timezone identifier
200
country: str      # ISO country code
201
region: str       # State/region code
202

203
# Data availability periods
204
hourly_start: datetime    # First available hourly observation
205
hourly_end: datetime      # Last available hourly observation  
206
daily_start: datetime     # First available daily observation
207
daily_end: datetime       # Last available daily observation
208
monthly_start: datetime   # First available monthly observation
209
monthly_end: datetime     # Last available monthly observation
210

211
# Computed fields (when using nearby())
212
distance: float   # Distance from query point in meters (when using nearby())
213
```