0
# Elevation and Geography
1

2
Retrieve elevation data for specific locations or along paths, and access timezone information for any location worldwide with support for various coordinate formats and sampling options.
3

4
## Capabilities
5

6
### Elevation Data
7

8
Get elevation information for specific coordinates or sample elevation along a path.
9

10
```python { .api }
11
def elevation(client, locations):
12
    """
13
    Get elevation data for specific locations.
14
    
15
    Args:
16
        client (Client): Google Maps API client instance
17
        locations (list): List of coordinate points as (lat, lng) tuples,
18
                         coordinate dicts, or encoded polyline string
19
    
20
    Returns:
21
        list: List of elevation result dictionaries containing:
22
              - elevation: Height above sea level in meters
23
              - location: Lat/lng coordinates
24
              - resolution: Accuracy of elevation data in meters
25
    
26
    Raises:
27
        googlemaps.exceptions.ApiError: When API returns an error
28
        googlemaps.exceptions.TransportError: When HTTP request fails
29
        googlemaps.exceptions.Timeout: When request times out
30
    """
31

32
def elevation_along_path(client, path, samples):
33
    """
34
    Get elevation data along a path with specified sampling.
35
    
36
    Args:
37
        client (Client): Google Maps API client instance
38
        path (list): Path as list of (lat, lng) tuples, coordinate dicts,
39
                    or encoded polyline string
40
        samples (int): Number of sample points along path (max 512)
41
    
42
    Returns:
43
        list: List of elevation result dictionaries with elevation data
44
              sampled along the path at equal intervals
45
    
46
    Raises:
47
        googlemaps.exceptions.ApiError: When API returns an error
48
        googlemaps.exceptions.TransportError: When HTTP request fails
49
        googlemaps.exceptions.Timeout: When request times out
50
    """
51
```
52

53
### Timezone Information
54

55
Get timezone data for any location including offset information and timezone identifiers.
56

57
```python { .api }
58
def timezone(client, location, timestamp=None, language=None):
59
    """
60
    Get timezone information for a location.
61
    
62
    Args:
63
        client (Client): Google Maps API client instance
64
        location (tuple): Coordinates as (lat, lng) tuple or coordinate dict
65
        timestamp (datetime): Timestamp for timezone calculation (default: current time)
66
        language (str): Language code for timezone names (ISO 639-1)
67
    
68
    Returns:
69
        dict: Timezone information containing:
70
              - timeZoneId: IANA timezone identifier (e.g., "America/New_York")
71
              - timeZoneName: Human-readable timezone name
72
              - dstOffset: Daylight saving offset in seconds
73
              - rawOffset: Base timezone offset from UTC in seconds
74
              - status: Request status
75
    
76
    Raises:
77
        googlemaps.exceptions.ApiError: When API returns an error
78
        googlemaps.exceptions.TransportError: When HTTP request fails
79
        googlemaps.exceptions.Timeout: When request times out
80
    """
81
```
82

83
## Usage Examples
84

85
### Basic Elevation Lookup
86

87
```python
88
import googlemaps
89

90
gmaps = googlemaps.Client(key='YOUR_API_KEY')
91

92
# Get elevation for specific coordinates
93
locations = [
94
    (40.714728, -73.998672),  # NYC coordinates
95
    (34.052235, -118.243683), # LA coordinates
96
    (41.878113, -87.629799)   # Chicago coordinates
97
]
98

99
elevation_result = gmaps.elevation(locations)
100

101
# Display elevation data
102
for result in elevation_result:
103
    lat = result['location']['lat']
104
    lng = result['location']['lng']
105
    elevation = result['elevation']
106
    resolution = result['resolution']
107
    
108
    print(f"Location: ({lat:.6f}, {lng:.6f})")
109
    print(f"Elevation: {elevation:.2f} meters")
110
    print(f"Resolution: {resolution:.2f} meters")
111
    print("---")
112
```
113

114
### Elevation Along a Route
115

116
```python
117
import googlemaps
118

119
gmaps = googlemaps.Client(key='YOUR_API_KEY')
120

121
# Define a path (e.g., hiking trail coordinates)
122
trail_path = [
123
    (36.579, -118.292),   # Start point
124
    (36.582, -118.295),   # Point 2
125
    (36.585, -118.298),   # Point 3
126
    (36.588, -118.301),   # End point
127
]
128

129
# Sample elevation along the path
130
elevation_profile = gmaps.elevation_along_path(
131
    path=trail_path,
132
    samples=20  # Get 20 elevation points along the path
133
)
134

135
# Create elevation profile
136
print("Elevation Profile:")
137
for i, point in enumerate(elevation_profile):
138
    elevation = point['elevation']
139
    print(f"Point {i+1}: {elevation:.1f}m")
140

141
# Calculate elevation gain/loss
142
elevations = [point['elevation'] for point in elevation_profile]
143
total_gain = sum(max(0, elevations[i] - elevations[i-1]) for i in range(1, len(elevations)))
144
total_loss = sum(max(0, elevations[i-1] - elevations[i]) for i in range(1, len(elevations)))
145

146
print(f"\nTotal elevation gain: {total_gain:.1f}m")
147
print(f"Total elevation loss: {total_loss:.1f}m")
148
```
149

150
### Using Encoded Polylines for Elevation
151

152
```python
153
import googlemaps
154

155
gmaps = googlemaps.Client(key='YOUR_API_KEY')
156

157
# Use an encoded polyline (from directions API)
158
directions_result = gmaps.directions(
159
    origin="Denver, CO",
160
    destination="Boulder, CO"
161
)
162

163
# Extract polyline from route
164
polyline = directions_result[0]['overview_polyline']['points']
165

166
# Get elevation along the route
167
route_elevation = gmaps.elevation_along_path(
168
    path=polyline,
169
    samples=50  # Sample 50 points along route
170
)
171

172
# Find highest and lowest points
173
elevations = [point['elevation'] for point in route_elevation]
174
max_elevation = max(elevations)
175
min_elevation = min(elevations)
176

177
print(f"Route elevation range: {min_elevation:.0f}m - {max_elevation:.0f}m")
178
print(f"Elevation difference: {max_elevation - min_elevation:.0f}m")
179
```
180

181
### Basic Timezone Lookup
182

183
```python
184
import googlemaps
185
from datetime import datetime
186

187
gmaps = googlemaps.Client(key='YOUR_API_KEY')
188

189
# Get timezone for coordinates
190
location = (37.7749, -122.4194)  # San Francisco
191

192
timezone_result = gmaps.timezone(location)
193

194
print(f"Timezone ID: {timezone_result['timeZoneId']}")
195
print(f"Timezone Name: {timezone_result['timeZoneName']}")
196
print(f"UTC Offset: {timezone_result['rawOffset'] / 3600:.1f} hours")
197
print(f"DST Offset: {timezone_result['dstOffset'] / 3600:.1f} hours")
198

199
# Calculate local time
200
utc_offset = (timezone_result['rawOffset'] + timezone_result['dstOffset']) / 3600
201
print(f"Total offset from UTC: {utc_offset:.1f} hours")
202
```
203

204
### Timezone with Specific Timestamp
205

206
```python
207
import googlemaps
208
from datetime import datetime, timezone
209

210
gmaps = googlemaps.Client(key='YOUR_API_KEY')
211

212
# Check timezone for a specific date (useful for historical data)
213
location = (40.7128, -74.0060)  # New York City
214
specific_date = datetime(2024, 7, 15, 12, 0, 0)  # July 15, 2024 (summer)
215

216
summer_timezone = gmaps.timezone(
217
    location=location,
218
    timestamp=specific_date
219
)
220

221
print("Summer timezone info:")
222
print(f"  Timezone: {summer_timezone['timeZoneName']}")
223
print(f"  DST Offset: {summer_timezone['dstOffset'] / 3600:.1f} hours")
224

225
# Check same location in winter
226
winter_date = datetime(2024, 1, 15, 12, 0, 0)  # January 15, 2024 (winter)
227

228
winter_timezone = gmaps.timezone(
229
    location=location, 
230
    timestamp=winter_date
231
)
232

233
print("\nWinter timezone info:")
234
print(f"  Timezone: {winter_timezone['timeZoneName']}")
235
print(f"  DST Offset: {winter_timezone['dstOffset'] / 3600:.1f} hours")
236
```
237

238
### Multiple Location Timezone Lookup
239

240
```python
241
import googlemaps
242
from datetime import datetime
243

244
gmaps = googlemaps.Client(key='YOUR_API_KEY')
245

246
# Major cities around the world
247
cities = [
248
    ("New York", (40.7128, -74.0060)),
249
    ("London", (51.5074, -0.1278)),
250
    ("Tokyo", (35.6762, 139.6503)),
251
    ("Sydney", (-33.8688, 151.2093)),
252
    ("Dubai", (25.2048, 55.2708))
253
]
254

255
current_time = datetime.now()
256

257
print("Current timezone information:")
258
print("=" * 50)
259

260
for city_name, coordinates in cities:
261
    tz_info = gmaps.timezone(
262
        location=coordinates,
263
        timestamp=current_time,
264
        language="en"
265
    )
266
    
267
    # Calculate local offset
268
    total_offset = (tz_info['rawOffset'] + tz_info['dstOffset']) / 3600
269
    
270
    print(f"{city_name}:")
271
    print(f"  Timezone: {tz_info['timeZoneName']}")
272
    print(f"  UTC Offset: {total_offset:+.1f} hours")
273
    print(f"  IANA ID: {tz_info['timeZoneId']}")
274
    print()
275
```
276

277
### Combined Elevation and Geography Analysis
278

279
```python
280
import googlemaps
281
from datetime import datetime
282

283
gmaps = googlemaps.Client(key='YOUR_API_KEY')
284

285
def analyze_location(name, coordinates):
286
    """Analyze both elevation and timezone for a location."""
287
    print(f"Analysis for {name}:")
288
    print("=" * 30)
289
    
290
    # Get elevation
291
    elevation_result = gmaps.elevation([coordinates])
292
    elevation_data = elevation_result[0]
293
    
294
    print(f"Coordinates: {coordinates}")
295
    print(f"Elevation: {elevation_data['elevation']:.1f} meters above sea level")
296
    print(f"Elevation resolution: {elevation_data['resolution']:.1f} meters")
297
    
298
    # Get timezone
299
    timezone_result = gmaps.timezone(
300
        location=coordinates,
301
        timestamp=datetime.now()
302
    )
303
    
304
    total_offset = (timezone_result['rawOffset'] + timezone_result['dstOffset']) / 3600
305
    print(f"Timezone: {timezone_result['timeZoneName']}")
306
    print(f"UTC Offset: {total_offset:+.1f} hours")
307
    print()
308

309
# Analyze multiple interesting locations
310
locations = [
311
    ("Mount Everest Base Camp", (28.0018, 86.8528)),
312
    ("Death Valley (lowest point in North America)", (36.2548, -116.8275)),
313
    ("Denver (Mile High City)", (39.7392, -104.9903)),
314
    ("Amsterdam (below sea level)", (52.3676, 4.9041))
315
]
316

317
for name, coords in locations:
318
    analyze_location(name, coords)
319
```
320

321
### Elevation Profile Visualization Data
322

323
```python
324
import googlemaps
325

326
gmaps = googlemaps.Client(key='YOUR_API_KEY')
327

328
def get_route_elevation_profile(origin, destination, samples=100):
329
    """Get elevation profile for a route."""
330
    
331
    # Get route directions first
332
    directions = gmaps.directions(origin, destination)
333
    route_polyline = directions[0]['overview_polyline']['points']
334
    
335
    # Get elevation along route
336
    elevation_data = gmaps.elevation_along_path(
337
        path=route_polyline,
338
        samples=samples
339
    )
340
    
341
    # Extract data for visualization
342
    distances = []
343
    elevations = []
344
    
345
    # Calculate approximate distances (simplified)
346
    total_distance = directions[0]['legs'][0]['distance']['value']  # meters
347
    
348
    for i, point in enumerate(elevation_data):
349
        distance = (i / (len(elevation_data) - 1)) * total_distance / 1000  # km
350
        distances.append(distance)
351
        elevations.append(point['elevation'])
352
    
353
    return {
354
        'distances_km': distances,
355
        'elevations_m': elevations,
356
        'route_info': {
357
            'origin': directions[0]['legs'][0]['start_address'],
358
            'destination': directions[0]['legs'][0]['end_address'],
359
            'total_distance_km': total_distance / 1000,
360
            'total_duration': directions[0]['legs'][0]['duration']['text']
361
        }
362
    }
363

364
# Example: Get elevation profile for a mountain route
365
profile = get_route_elevation_profile(
366
    "Boulder, CO",
367
    "Rocky Mountain National Park, CO"
368
)
369

370
print(f"Route: {profile['route_info']['origin']} to {profile['route_info']['destination']}")
371
print(f"Distance: {profile['route_info']['total_distance_km']:.1f} km")
372
print(f"Duration: {profile['route_info']['total_duration']}")
373
print("\nElevation profile (first 10 points):")
374

375
for i in range(min(10, len(profile['distances_km']))):
376
    dist = profile['distances_km'][i]
377
    elev = profile['elevations_m'][i]
378
    print(f"  {dist:.1f} km: {elev:.0f} m")
379
```