0
# Elevation Queries
1

2
Core functionality for retrieving elevation data at specific coordinates with support for both SRTM1 and SRTM3 data sources, automatic file downloading, and interpolation options.
3

4
## Capabilities
5

6
### Factory Function
7

8
Creates the main elevation data utility object with configurable data sources, caching options, and processing modes.
9

10
```python { .api }
11
def get_data(
12
    srtm1: bool = True,
13
    srtm3: bool = True, 
14
    leave_zipped: bool = False,
15
    file_handler: Optional[FileHandler] = None,
16
    use_included_urls: bool = True,
17
    batch_mode: bool = False,
18
    local_cache_dir: str = "",
19
    timeout: int = 0
20
) -> GeoElevationData
21
```
22

23
**Parameters:**
24
- `srtm1` (bool): Enable SRTM1 data (30m resolution, US only). Default: True
25
- `srtm3` (bool): Enable SRTM3 data (90m resolution, global). Default: True
26
- `leave_zipped` (bool): Store downloaded files as compressed zip files. Default: False
27
- `file_handler` (Optional[FileHandler]): Custom file handling implementation. Default: None
28
- `use_included_urls` (bool): Use pre-cached URL list for faster file discovery. Default: True
29
- `batch_mode` (bool): Memory-efficient mode that keeps only the most recent file in memory. Default: False
30
- `local_cache_dir` (str): Custom directory for caching SRTM files. Default: "" (uses ~/.cache/srtm/)
31
- `timeout` (int): Network timeout in seconds for file downloads. Default: 0 (uses default timeout)
32

33
**Returns:** GeoElevationData instance configured with specified options
34

35
**Usage Example:**
36
```python
37
import srtm
38

39
# Basic usage with default settings
40
elevation_data = srtm.get_data()
41

42
# Custom configuration for memory-efficient processing
43
elevation_data = srtm.get_data(
44
    srtm1=False,           # Disable SRTM1 to save bandwidth
45
    batch_mode=True,       # Enable memory-efficient mode
46
    local_cache_dir="./srtm_cache",  # Custom cache location
47
    timeout=30             # 30-second timeout
48
)
49
```
50

51
### Point Elevation Lookup
52

53
Retrieve elevation data for specific coordinates with optional approximation for improved accuracy.
54

55
```python { .api }
56
class GeoElevationData:
57
    def get_elevation(self, latitude: float, longitude: float, approximate: bool = False) -> Optional[float]: ...
58
```
59

60
**Parameters:**
61
- `latitude` (float): Latitude coordinate (-90 to 90 degrees)
62
- `longitude` (float): Longitude coordinate (-180 to 180 degrees)  
63
- `approximate` (bool): Use interpolation between nearby points for better accuracy. Default: False
64

65
**Returns:** Elevation in meters above sea level, or None if no data available
66

67
**Usage Example:**
68
```python
69
elevation_data = srtm.get_data()
70

71
# Basic elevation lookup
72
elevation = elevation_data.get_elevation(45.8566, 7.8566)
73
print(f"Elevation: {elevation} meters")
74

75
# More accurate lookup with approximation
76
elevation_approx = elevation_data.get_elevation(45.8566, 7.8566, approximate=True)
77
print(f"Approximate elevation: {elevation_approx} meters")
78

79
# Handle missing data
80
elevation = elevation_data.get_elevation(0.0, 0.0)  # Ocean coordinates
81
if elevation is None:
82
    print("No elevation data available for these coordinates")
83
```
84

85
### SRTM File Access
86

87
Direct access to SRTM data files and metadata for advanced processing.
88

89
```python { .api }
90
class GeoElevationData:
91
    def get_file(self, latitude: float, longitude: float) -> Optional[GeoElevationFile]: ...
92
    def get_file_name(self, latitude: float, longitude: float) -> Optional[str]: ...
93
```
94

95
**get_file()** returns the SRTM file object containing the specified coordinates:
96
- **Parameters:** `latitude` (float), `longitude` (float)
97
- **Returns:** GeoElevationFile instance or None if no file covers the coordinates
98

99
**get_file_name()** returns the standard SRTM filename for the coordinates:
100
- **Parameters:** `latitude` (float), `longitude` (float)  
101
- **Returns:** Filename string (e.g., "N45E007.hgt") or None if no file exists
102

103
**Usage Example:**
104
```python
105
elevation_data = srtm.get_data()
106

107
# Get the SRTM file for specific coordinates
108
srtm_file = elevation_data.get_file(45.8566, 7.8566)
109
if srtm_file:
110
    print(f"File: {srtm_file.file_name}")
111
    print(f"Coverage: {srtm_file.latitude}, {srtm_file.longitude}")
112
    print(f"Resolution: {srtm_file.resolution} degrees per pixel")
113

114
# Get just the filename
115
filename = elevation_data.get_file_name(45.8566, 7.8566)
116
print(f"SRTM filename: {filename}")
117
```
118

119
### SRTM File Operations
120

121
Direct operations on individual SRTM files for granular control over elevation queries.
122

123
```python { .api }
124
class GeoElevationFile:
125
    file_name: str
126
    latitude: float
127
    longitude: float
128
    resolution: float
129
    square_side: int
130
    
131
    def get_elevation(self, latitude: float, longitude: float, approximate: bool = False) -> Optional[float]: ...
132
    def get_row_and_column(self, latitude: float, longitude: float) -> Tuple[int, int]: ...
133
    def get_lat_and_long(self, row: int, column: int) -> Tuple[float, float]: ...
134
    def get_elevation_from_row_and_column(self, row: int, column: int) -> Optional[float]: ...
135
    def parse_file_name_starting_position(self) -> None: ...
136
```
137

138
**Properties:**
139
- `file_name`: SRTM filename (e.g., "N45E007.hgt")
140
- `latitude`: Lower-left latitude of file coverage
141
- `longitude`: Lower-left longitude of file coverage
142
- `resolution`: Degrees per pixel
143
- `square_side`: File dimensions in pixels (typically 1201 or 3601)
144

145
**get_elevation()**: Get elevation from this specific file
146
- Validates that coordinates are within file bounds
147
- Same parameters and behavior as GeoElevationData.get_elevation()
148

149
**get_row_and_column()**: Convert geographic coordinates to pixel indices
150
- **Returns:** Tuple of (row, column) indices within the file
151

152
**get_lat_and_long()**: Convert pixel indices back to geographic coordinates  
153
- **Parameters:** `row` (int), `column` (int)
154
- **Returns:** Tuple of (latitude, longitude) coordinates
155

156
**get_elevation_from_row_and_column()**: Get elevation value from specific pixel location
157
- **Parameters:** `row` (int), `column` (int) - Pixel indices within the file
158
- **Returns:** Elevation in meters, or None if invalid location or no data
159

160
**parse_file_name_starting_position()**: Parse SRTM filename to extract geographic bounds
161
- **Parameters:** None (uses internal file_name attribute)
162
- **Returns:** None (sets internal latitude and longitude attributes)
163

164
**Usage Example:**
165
```python
166
elevation_data = srtm.get_data()
167
srtm_file = elevation_data.get_file(45.8566, 7.8566)
168

169
if srtm_file:
170
    # Get elevation from specific file
171
    elevation = srtm_file.get_elevation(45.8566, 7.8566)
172
    
173
    # Convert coordinates to pixel indices
174
    row, col = srtm_file.get_row_and_column(45.8566, 7.8566)
175
    print(f"Pixel location: row {row}, column {col}")
176
    
177
    # Get elevation directly from pixel coordinates
178
    pixel_elevation = srtm_file.get_elevation_from_row_and_column(int(row), int(col))
179
    print(f"Pixel elevation: {pixel_elevation}m")
180
    
181
    # Convert back to coordinates
182
    lat, lon = srtm_file.get_lat_and_long(int(row), int(col))
183
    print(f"Coordinates: {lat}, {lon}")
184
    
185
    # Display file information
186
    print(f"File: {srtm_file}")  # Uses __str__ method
187
```
188

189
## Error Handling
190

191
Common error conditions when working with elevation queries:
192

193
- **Network Errors**: Connection failures during SRTM file downloads
194
- **Missing Data**: No SRTM coverage for requested coordinates (returns None)
195
- **Invalid Coordinates**: Latitude/longitude values outside valid ranges
196
- **File Corruption**: Downloaded SRTM files that are corrupted or invalid
197
- **Disk Space**: Insufficient space for downloading and caching SRTM files
198
- **Permission Errors**: Unable to write to cache directory