0
# Figure and Map Management
1

2
Core functionality for creating and managing interactive map figures with Google Maps integration, viewport control, and layer composition. The Figure is the main entry point for displaying maps in Jupyter notebooks.
3

4
## Capabilities
5

6
### Configuration
7

8
Configure global settings for accessing the Google Maps API.
9

10
```python { .api }
11
def configure(api_key=None):
12
    """
13
    Configure access to the GoogleMaps API.
14

15
    Parameters:
16
    - api_key (str, optional): String denoting the key to use when accessing Google maps, or None to not pass an API key
17

18
    Returns:
19
    None
20
    """
21
```
22

23
### Figure Creation
24

25
Create a new map figure with customizable display options and initial viewport settings.
26

27
```python { .api }
28
def figure(display_toolbar=True, display_errors=True, zoom_level=None, tilt=45, center=None, layout=None, map_type='ROADMAP', mouse_handling='COOPERATIVE'):
29
    """
30
    Create a gmaps figure.
31

32
    Parameters:
33
    - display_toolbar (bool): Whether to display the toolbar
34
    - display_errors (bool): Whether to display error messages
35
    - zoom_level (int, optional): Initial zoom level (0-21)
36
    - tilt (int): Tilt angle in degrees (0 or 45)
37
    - center (tuple, optional): Initial center as (latitude, longitude)
38
    - layout (dict, optional): Widget layout configuration
39
    - map_type (str): Map display type ('ROADMAP', 'SATELLITE', 'HYBRID', 'TERRAIN')
40
    - mouse_handling (str): Mouse interaction mode ('COOPERATIVE', 'GREEDY', 'NONE', 'AUTO')
41

42
    Returns:
43
    Figure: A new Figure instance
44
    """
45
```
46

47
### Figure Widget
48

49
Main figure widget for displaying maps with layers and interactive elements.
50

51
```python { .api }
52
class Figure:
53
    """
54
    Figure widget for displaying Google Maps in Jupyter notebooks.
55
    
56
    Attributes:
57
    - map_type (str): Map display type
58
    - tilt (int): Tilt angle in degrees
59
    - mouse_handling (str): Mouse interaction mode
60
    - layout (dict): Widget layout configuration
61
    """
62
    
63
    def add_layer(self, layer):
64
        """
65
        Add a data layer to the figure.
66

67
        Parameters:
68
        - layer: Layer instance (Heatmap, Markers, GeoJson, etc.)
69

70
        Returns:
71
        None
72
        """
73
```
74

75
### Map Widget
76

77
Base map widget that handles Google Maps integration and viewport management.
78

79
```python { .api }
80
class Map:
81
    """
82
    Base map widget for Google Maps integration.
83
    
84
    Attributes:
85
    - layers (list): List of map layers
86
    - data_bounds (list): Geographic bounds of data as [[south, west], [north, east]]
87
    - initial_viewport (InitialViewport): Initial zoom and center settings
88
    """
89
    
90
    def add_layer(self, layer):
91
        """
92
        Add layer to map.
93

94
        Parameters:
95
        - layer: Layer instance to add
96

97
        Returns:
98
        None
99
        """
100
```
101

102
### Viewport Configuration
103

104
Configure the initial viewport settings for maps.
105

106
```python { .api }
107
class InitialViewport:
108
    """
109
    Viewport configuration for maps.
110
    
111
    Attributes:
112
    - zoom_level (int): Zoom level (0-21)
113
    - center (tuple): Center coordinates as (latitude, longitude)
114
    """
115
    
116
    @staticmethod
117
    def from_data_bounds():
118
        """
119
        Create viewport centered on data bounds.
120

121
        Returns:
122
        InitialViewport: Configured viewport that automatically centers on map data
123
        """
124
    
125
    @staticmethod
126
    def from_zoom_center(zoom_level, center):
127
        """
128
        Create viewport with explicit zoom and center.
129

130
        Parameters:
131
        - zoom_level (int): Zoom level (0-21)
132
        - center (tuple): Center as (latitude, longitude)
133

134
        Returns:
135
        InitialViewport: Configured viewport
136
        """
137
```
138

139
## Usage Examples
140

141
### Basic Figure Creation
142

143
```python
144
import gmaps
145

146
# Configure API access
147
gmaps.configure(api_key="YOUR_API_KEY")
148

149
# Create a basic figure
150
fig = gmaps.figure()
151
fig
152
```
153

154
### Customized Figure
155

156
```python
157
import gmaps
158

159
# Create figure with custom settings
160
fig = gmaps.figure(
161
    center=(37.7749, -122.4194),  # San Francisco
162
    zoom_level=10,
163
    map_type='SATELLITE',
164
    mouse_handling='GREEDY',
165
    layout={'height': '600px', 'width': '100%'}
166
)
167
fig
168
```
169

170
### Adding Multiple Layers
171

172
```python
173
import gmaps
174
import gmaps.datasets
175

176
gmaps.configure(api_key="YOUR_API_KEY")
177

178
# Create figure
179
fig = gmaps.figure(center=(37.7749, -122.4194), zoom_level=10)
180

181
# Add heatmap layer
182
earthquake_data = gmaps.datasets.load_dataset_as_df('earthquakes')
183
locations = earthquake_data[['latitude', 'longitude']]
184
heatmap = gmaps.heatmap_layer(locations)
185
fig.add_layer(heatmap)
186

187
# Add marker layer
188
marker_locations = [(37.7749, -122.4194), (37.7849, -122.4094)]
189
markers = gmaps.marker_layer(marker_locations)
190
fig.add_layer(markers)
191

192
fig
193
```