0
# Direction and Route Planning
1
2
Generate and display routes between locations with support for multiple transportation modes, waypoints, and route customization options. Perfect for showing travel paths and analyzing routing scenarios.
3
4
## Capabilities
5
6
### Directions Layer Creation
7
8
Create route layers between start and end points with optional waypoints and travel preferences.
9
10
```python { .api }
11
def directions_layer(start, end, waypoints=None, avoid_ferries=False, travel_mode='DRIVING', avoid_highways=False, avoid_tolls=False, optimize_waypoints=False, show_markers=True, show_route=True, stroke_color='#0088FF', stroke_weight=6.0, stroke_opacity=0.6):
12
"""
13
Create a directions layer showing routes.
14
15
Parameters:
16
- start (tuple): Starting location as (latitude, longitude)
17
- end (tuple): Ending location as (latitude, longitude)
18
- waypoints (list, optional): List of intermediate (latitude, longitude) points
19
- avoid_ferries (bool): Whether to avoid ferry routes
20
- travel_mode (str): Transportation mode ('BICYCLING', 'DRIVING', 'TRANSIT', 'WALKING')
21
- avoid_highways (bool): Whether to avoid highways
22
- avoid_tolls (bool): Whether to avoid toll roads
23
- optimize_waypoints (bool): Whether to optimize waypoint order
24
- show_markers (bool): Whether to show start/end markers
25
- show_route (bool): Whether to show the route line
26
- stroke_color (str): Route line color
27
- stroke_weight (float): Route line width in pixels
28
- stroke_opacity (float): Route line opacity (0.0-1.0)
29
30
Returns:
31
Directions: Directions layer instance
32
"""
33
```
34
35
### Directions Widget
36
37
Widget for displaying and managing route information.
38
39
```python { .api }
40
class Directions:
41
"""
42
Directions layer widget for route visualization.
43
44
Attributes:
45
- start (tuple): Starting location (latitude, longitude)
46
- end (tuple): Ending location (latitude, longitude)
47
- waypoints (list): List of intermediate points
48
- travel_mode (str): Transportation mode
49
- avoid_ferries (bool): Route preference for ferries
50
- avoid_highways (bool): Route preference for highways
51
- avoid_tolls (bool): Route preference for toll roads
52
- optimize_waypoints (bool): Whether waypoints are optimized
53
- show_markers (bool): Whether start/end markers are shown
54
- show_route (bool): Whether route line is shown
55
- stroke_color (str): Route line color
56
- stroke_weight (float): Route line width
57
- stroke_opacity (float): Route line opacity
58
"""
59
```
60
61
## Error Handling
62
63
```python { .api }
64
class DirectionsServiceException(RuntimeError):
65
"""
66
Raised when directions service fails.
67
68
Common causes:
69
- Invalid locations (not geocodable)
70
- No route available between points
71
- API quota exceeded
72
- Network connectivity issues
73
"""
74
```
75
76
## Usage Examples
77
78
### Basic Driving Directions
79
80
```python
81
import gmaps
82
83
gmaps.configure(api_key="YOUR_API_KEY")
84
85
# Define start and end points
86
start = (37.7749, -122.4194) # San Francisco
87
end = (34.0522, -118.2437) # Los Angeles
88
89
# Create directions layer
90
fig = gmaps.figure()
91
directions_layer = gmaps.directions_layer(start, end)
92
fig.add_layer(directions_layer)
93
fig
94
```
95
96
### Walking Directions with Waypoints
97
98
```python
99
import gmaps
100
101
gmaps.configure(api_key="YOUR_API_KEY")
102
103
# Define route points
104
start = (37.7749, -122.4194) # San Francisco City Hall
105
waypoints = [
106
(37.7849, -122.4094), # Golden Gate Park
107
(37.8024, -122.4058) # Presidio
108
]
109
end = (37.8199, -122.4783) # Golden Gate Bridge
110
111
# Create walking directions
112
fig = gmaps.figure()
113
directions_layer = gmaps.directions_layer(
114
start,
115
end,
116
waypoints=waypoints,
117
travel_mode='WALKING',
118
stroke_color='green',
119
stroke_weight=4.0
120
)
121
fig.add_layer(directions_layer)
122
fig
123
```
124
125
### Transit Directions
126
127
```python
128
import gmaps
129
130
gmaps.configure(api_key="YOUR_API_KEY")
131
132
# Public transit route
133
start = (37.7749, -122.4194) # Downtown SF
134
end = (37.7849, -122.4094) # Mission District
135
136
fig = gmaps.figure()
137
directions_layer = gmaps.directions_layer(
138
start,
139
end,
140
travel_mode='TRANSIT',
141
stroke_color='blue',
142
stroke_weight=5.0,
143
stroke_opacity=0.8
144
)
145
fig.add_layer(directions_layer)
146
fig
147
```
148
149
### Optimized Route with Preferences
150
151
```python
152
import gmaps
153
154
gmaps.configure(api_key="YOUR_API_KEY")
155
156
# Multiple delivery stops
157
start = (37.7749, -122.4194) # Warehouse
158
waypoints = [
159
(37.7649, -122.4294), # Stop 1
160
(37.7849, -122.4094), # Stop 2
161
(37.7949, -122.3994), # Stop 3
162
(37.7549, -122.4494) # Stop 4
163
]
164
end = (37.7749, -122.4194) # Return to warehouse
165
166
fig = gmaps.figure()
167
directions_layer = gmaps.directions_layer(
168
start,
169
end,
170
waypoints=waypoints,
171
travel_mode='DRIVING',
172
optimize_waypoints=True, # Find best order
173
avoid_tolls=True, # Avoid toll roads
174
avoid_highways=False, # Allow highways
175
stroke_color='red',
176
stroke_weight=4.0
177
)
178
fig.add_layer(directions_layer)
179
fig
180
```
181
182
### Bicycle Route
183
184
```python
185
import gmaps
186
187
gmaps.configure(api_key="YOUR_API_KEY")
188
189
start = (37.7749, -122.4194) # Start point
190
end = (37.7649, -122.4094) # End point
191
192
fig = gmaps.figure()
193
directions_layer = gmaps.directions_layer(
194
start,
195
end,
196
travel_mode='BICYCLING',
197
stroke_color='orange',
198
stroke_weight=3.0,
199
stroke_opacity=0.7
200
)
201
fig.add_layer(directions_layer)
202
fig
203
```
204
205
### Multiple Routes Comparison
206
207
```python
208
import gmaps
209
210
gmaps.configure(api_key="YOUR_API_KEY")
211
212
start = (37.7749, -122.4194)
213
end = (37.6879, -122.4702)
214
215
fig = gmaps.figure()
216
217
# Driving route
218
driving_layer = gmaps.directions_layer(
219
start, end,
220
travel_mode='DRIVING',
221
stroke_color='blue',
222
stroke_weight=4.0
223
)
224
fig.add_layer(driving_layer)
225
226
# Transit route
227
transit_layer = gmaps.directions_layer(
228
start, end,
229
travel_mode='TRANSIT',
230
stroke_color='green',
231
stroke_weight=4.0
232
)
233
fig.add_layer(transit_layer)
234
235
# Walking route
236
walking_layer = gmaps.directions_layer(
237
start, end,
238
travel_mode='WALKING',
239
stroke_color='red',
240
stroke_weight=3.0
241
)
242
fig.add_layer(walking_layer)
243
244
fig
245
```
246
247
### Route with Custom Styling
248
249
```python
250
import gmaps
251
252
gmaps.configure(api_key="YOUR_API_KEY")
253
254
start = (37.7749, -122.4194)
255
end = (37.7849, -122.4094)
256
257
fig = gmaps.figure()
258
directions_layer = gmaps.directions_layer(
259
start,
260
end,
261
travel_mode='DRIVING',
262
show_markers=True, # Show start/end markers
263
show_route=True, # Show route line
264
stroke_color='purple', # Custom color
265
stroke_weight=8.0, # Thick line
266
stroke_opacity=0.9, # High opacity
267
avoid_highways=True # Route preference
268
)
269
fig.add_layer(directions_layer)
270
fig
271
```
272
273
## Error Handling Example
274
275
```python
276
import gmaps
277
278
gmaps.configure(api_key="YOUR_API_KEY")
279
280
try:
281
# Invalid coordinates might cause an error
282
start = (0, 0) # Middle of ocean
283
end = (90, 180) # Invalid location
284
285
fig = gmaps.figure()
286
directions_layer = gmaps.directions_layer(start, end)
287
fig.add_layer(directions_layer)
288
fig
289
290
except gmaps.DirectionsServiceException as e:
291
print(f"Directions error: {e}")
292
# Handle error appropriately
293
```