0
# gmaps
1

2
A comprehensive Jupyter notebook plugin for embedding interactive Google Maps with rich visualization capabilities. It enables data scientists to create heatmaps, choropleth maps using GeoJSON data, symbol layers for point data visualization, and interactive drawing tools directly within Jupyter notebooks.
3

4
## Package Information
5

6
- **Package Name**: gmaps
7
- **Package Type**: pypi
8
- **Language**: Python
9
- **Installation**: `pip install gmaps`
10

11
## Core Imports
12

13
```python
14
import gmaps
15
```
16

17
Common for working with maps:
18

19
```python
20
import gmaps
21
gmaps.configure(api_key="YOUR_API_KEY")
22
```
23

24
## Basic Usage
25

26
```python
27
import gmaps
28
import gmaps.datasets
29

30
# Configure API key
31
gmaps.configure(api_key="YOUR_API_KEY")
32

33
# Create a figure
34
fig = gmaps.figure()
35

36
# Load sample earthquake data
37
earthquake_data = gmaps.datasets.load_dataset_as_df('earthquakes')
38
locations = earthquake_data[['latitude', 'longitude']]
39
magnitudes = earthquake_data['magnitude']
40

41
# Add a heatmap layer
42
heatmap_layer = gmaps.heatmap_layer(locations, weights=magnitudes)
43
fig.add_layer(heatmap_layer)
44

45
# Display the map
46
fig
47
```
48

49
## Architecture
50

51
The gmaps package is built around a widget-based architecture:
52

53
- **Figure**: Top-level container that manages the map display and layers
54
- **Map**: Core map widget that handles Google Maps integration and viewport
55
- **Layers**: Modular visualization components (heatmaps, markers, GeoJSON, etc.)
56
- **Drawing Tools**: Interactive tools for user-generated content
57
- **Configuration**: API key management and display options
58

59
This design enables flexible composition of visualizations and seamless integration with Jupyter's interactive environment.
60

61
## Capabilities
62

63
### Figure and Map Management
64

65
Core functionality for creating and managing interactive map figures with Google Maps integration, viewport control, and layer composition.
66

67
```python { .api }
68
def configure(api_key=None): ...
69
def figure(display_toolbar=True, display_errors=True, zoom_level=None, tilt=45, center=None, layout=None, map_type='ROADMAP', mouse_handling='COOPERATIVE'): ...
70

71
class Figure:
72
    def add_layer(self, layer): ...
73

74
class Map:
75
    def add_layer(self, layer): ...
76
```
77

78
[Figure and Map Management](./figure-map.md)
79

80
### Heatmap Visualization
81

82
Create density visualizations showing geographic patterns in point data, with support for weighted heatmaps, custom gradients, and styling options.
83

84
```python { .api }
85
def heatmap_layer(locations, weights=None, max_intensity=None, dissipating=True, point_radius=None, opacity=0.6, gradient=None): ...
86

87
class Heatmap:
88
    locations: list
89
    max_intensity: float
90
    point_radius: int
91
    dissipating: bool
92
    opacity: float
93
    gradient: list
94

95
class WeightedHeatmap:
96
    locations: list
97
    weights: list
98
```
99

100
[Heatmap Visualization](./heatmap.md)
101

102
### Marker and Symbol Layers  
103

104
Display point data using markers and customizable SVG symbols with hover text, info boxes, and flexible styling options for geographic data visualization.
105

106
```python { .api }
107
def marker_layer(locations, hover_text='', label='', info_box_content=None, display_info_box=None): ...
108
def symbol_layer(locations, hover_text='', fill_color=None, fill_opacity=1.0, stroke_color=None, stroke_opacity=1.0, scale=3, info_box_content=None, display_info_box=None): ...
109

110
class Markers:
111
    markers: list
112

113
class Marker:
114
    location: tuple
115
    hover_text: str
116
    label: str
117
    display_info_box: bool
118
    info_box_content: str
119

120
class Symbol:
121
    location: tuple
122
    fill_color: str
123
    fill_opacity: float
124
    stroke_color: str
125
    stroke_opacity: float
126
    scale: float
127
```
128

129
[Marker and Symbol Layers](./markers.md)
130

131
### GeoJSON Visualization
132

133
Render geographic features from GeoJSON data including countries, regions, and custom shapes with choropleth mapping capabilities and styling controls.
134

135
```python { .api }
136
def geojson_layer(geojson, fill_color=None, fill_opacity=0.4, stroke_color=None, stroke_opacity=1.0, stroke_weight=1.0): ...
137

138
class GeoJson:
139
    features: list
140

141
class GeoJsonFeature:
142
    feature: dict
143
    fill_color: str
144
    fill_opacity: float
145
    stroke_color: str
146
    stroke_opacity: float
147
    stroke_weight: float
148
```
149

150
[GeoJSON Visualization](./geojson.md)
151

152
### Direction and Route Planning
153

154
Generate and display routes between locations with support for multiple transportation modes, waypoints, and route customization options.
155

156
```python { .api }
157
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): ...
158

159
class Directions:
160
    start: tuple
161
    end: tuple
162
    waypoints: list
163
    travel_mode: str
164
    avoid_ferries: bool
165
    avoid_highways: bool
166
    avoid_tolls: bool
167
    stroke_color: str
168
    stroke_weight: float
169
    stroke_opacity: float
170
```
171

172
[Direction and Route Planning](./directions.md)
173

174
### Interactive Drawing Tools
175

176
Enable users to draw and edit geometric features directly on the map including lines, polygons, circles, and markers with customizable styling.
177

178
```python { .api }
179
def drawing_layer(features=None, mode='MARKER', show_controls=True, marker_options=None, line_options=None, polygon_options=None, circle_options=None): ...
180

181
class Drawing:
182
    features: list
183
    mode: str
184
    show_controls: bool
185

186
class Line:
187
    start: tuple
188
    end: tuple
189
    stroke_color: str
190
    stroke_weight: float
191
    stroke_opacity: float
192

193
class Polygon:
194
    path: list
195
    stroke_color: str
196
    stroke_weight: float
197
    stroke_opacity: float
198
    fill_color: str
199
    fill_opacity: float
200

201
class Circle:
202
    center: tuple
203
    radius: float
204
    stroke_color: str
205
    stroke_weight: float
206
    stroke_opacity: float
207
    fill_color: str
208
    fill_opacity: float
209
```
210

211
[Interactive Drawing Tools](./drawing.md)
212

213
### Transportation and Traffic Layers
214

215
Display real-time and static transportation information including traffic conditions, public transit routes, and bicycling paths.
216

217
```python { .api }
218
def traffic_layer(auto_refresh=True): ...
219
def transit_layer(): ...
220
def bicycling_layer(): ...
221

222
class Traffic:
223
    auto_refresh: bool
224

225
class Transit: ...
226

227
class Bicycling: ...
228
```
229

230
[Transportation and Traffic Layers](./transportation.md)
231

232
### Built-in Datasets and Geometries
233

234
Access curated datasets and GeoJSON geometries for common use cases including earthquakes, taxi rides, and geographic boundaries.
235

236
```python { .api }
237
# Dataset functions
238
def gmaps.datasets.list_datasets(): ...
239
def gmaps.datasets.dataset_metadata(dataset_name): ...
240
def gmaps.datasets.load_dataset(dataset_name): ...
241
def gmaps.datasets.load_dataset_as_df(dataset_name): ...
242

243
# Geometry functions  
244
def gmaps.geojson_geometries.list_geometries(): ...
245
def gmaps.geojson_geometries.geometry_metadata(geometry_name): ...
246
def gmaps.geojson_geometries.load_geometry(geometry_name): ...
247
```
248

249
[Built-in Datasets and Geometries](./datasets.md)
250

251
## Common Types
252

253
```python { .api }
254
# Location coordinates
255
LocationType = tuple[float, float]  # (latitude, longitude)
256

257
# Map display types
258
MapType = Literal['ROADMAP', 'SATELLITE', 'HYBRID', 'TERRAIN']
259

260
# Mouse interaction modes
261
MouseHandling = Literal['COOPERATIVE', 'GREEDY', 'NONE', 'AUTO']
262

263
# Transportation modes
264
TravelMode = Literal['BICYCLING', 'DRIVING', 'TRANSIT', 'WALKING']
265

266
# Color specifications
267
ColorType = str  # CSS color names, hex codes, or RGB values
268

269
# Layout configuration
270
LayoutType = dict  # Widget layout parameters
271
```
272

273
## Error Handling
274

275
```python { .api }
276
class InvalidGeoJson(Exception):
277
    """Raised when invalid GeoJSON is provided"""
278

279
class DirectionsServiceException(RuntimeError):
280
    """Raised when directions service fails"""
281

282
class InvalidPointException(Exception):
283
    """Raised when invalid location coordinates are provided"""
284

285
class InvalidWeightException(Exception):
286
    """Raised when weight arrays don't match location arrays or contain invalid values"""
287
```