0
# Built-in Datasets and Geometries
1
2
Access curated datasets and GeoJSON geometries for common use cases including earthquakes, taxi rides, and geographic boundaries. These built-in resources provide ready-to-use data for creating visualizations and testing applications.
3
4
## Capabilities
5
6
### Dataset Functions
7
8
Access and load curated datasets for common visualization scenarios.
9
10
```python { .api }
11
def gmaps.datasets.list_datasets():
12
"""
13
List available built-in datasets.
14
15
Returns:
16
list: List of dataset names
17
"""
18
19
def gmaps.datasets.dataset_metadata(dataset_name):
20
"""
21
Get metadata for a dataset.
22
23
Parameters:
24
- dataset_name (str): Name of the dataset
25
26
Returns:
27
dict: Dictionary with dataset information including description, size, and columns
28
"""
29
30
def gmaps.datasets.load_dataset(dataset_name):
31
"""
32
Load a dataset as list of tuples.
33
34
Parameters:
35
- dataset_name (str): Name of the dataset to load
36
37
Returns:
38
list: List of data tuples
39
"""
40
41
def gmaps.datasets.load_dataset_as_df(dataset_name):
42
"""
43
Load a dataset as pandas DataFrame.
44
45
Parameters:
46
- dataset_name (str): Name of the dataset to load
47
48
Returns:
49
pandas.DataFrame: Dataset as DataFrame with proper column names
50
"""
51
```
52
53
### GeoJSON Geometry Functions
54
55
Access built-in GeoJSON geometries for geographic boundaries and regions.
56
57
```python { .api }
58
def gmaps.geojson_geometries.list_geometries():
59
"""
60
List available built-in geometries.
61
62
Returns:
63
list: List of geometry names
64
"""
65
66
def gmaps.geojson_geometries.geometry_metadata(geometry_name):
67
"""
68
Get metadata for a geometry.
69
70
Parameters:
71
- geometry_name (str): Name of the geometry
72
73
Returns:
74
dict: Dictionary with geometry information including description and feature count
75
"""
76
77
def gmaps.geojson_geometries.load_geometry(geometry_name):
78
"""
79
Load a GeoJSON geometry.
80
81
Parameters:
82
- geometry_name (str): Name of the geometry to load
83
84
Returns:
85
dict: GeoJSON geometry dictionary (FeatureCollection)
86
"""
87
```
88
89
## Usage Examples
90
91
### Exploring Available Datasets
92
93
```python
94
import gmaps.datasets
95
96
# List all available datasets
97
datasets = gmaps.datasets.list_datasets()
98
print("Available datasets:", datasets)
99
100
# Get metadata for a specific dataset
101
if 'earthquakes' in datasets:
102
metadata = gmaps.datasets.dataset_metadata('earthquakes')
103
print("Earthquake dataset metadata:", metadata)
104
```
105
106
### Loading and Using Earthquake Data
107
108
```python
109
import gmaps
110
import gmaps.datasets
111
112
gmaps.configure(api_key="YOUR_API_KEY")
113
114
# Load earthquake dataset
115
earthquake_data = gmaps.datasets.load_dataset_as_df('earthquakes')
116
print(f"Loaded {len(earthquake_data)} earthquake records")
117
print("Columns:", earthquake_data.columns.tolist())
118
119
# Extract locations and magnitudes
120
locations = earthquake_data[['latitude', 'longitude']]
121
magnitudes = earthquake_data['magnitude']
122
123
# Create heatmap visualization
124
fig = gmaps.figure()
125
heatmap_layer = gmaps.heatmap_layer(
126
locations,
127
weights=magnitudes,
128
max_intensity=8.0
129
)
130
fig.add_layer(heatmap_layer)
131
fig
132
```
133
134
### Using Built-in Geometries
135
136
```python
137
import gmaps
138
import gmaps.geojson_geometries
139
140
gmaps.configure(api_key="YOUR_API_KEY")
141
142
# List available geometries
143
geometries = gmaps.geojson_geometries.list_geometries()
144
print("Available geometries:", geometries)
145
146
# Load country boundaries
147
if 'countries' in geometries:
148
countries = gmaps.geojson_geometries.load_geometry('countries')
149
150
# Create GeoJSON layer
151
fig = gmaps.figure()
152
geojson_layer = gmaps.geojson_layer(
153
countries,
154
fill_color='lightblue',
155
fill_opacity=0.4,
156
stroke_color='blue'
157
)
158
fig.add_layer(geojson_layer)
159
fig
160
```
161
162
### Taxi Ride Analysis
163
164
```python
165
import gmaps
166
import gmaps.datasets
167
168
gmaps.configure(api_key="YOUR_API_KEY")
169
170
# Load taxi ride data (if available)
171
try:
172
taxi_data = gmaps.datasets.load_dataset_as_df('taxi_rides')
173
174
# Extract pickup and dropoff locations
175
pickup_locations = taxi_data[['pickup_latitude', 'pickup_longitude']]
176
dropoff_locations = taxi_data[['dropoff_latitude', 'dropoff_longitude']]
177
178
fig = gmaps.figure()
179
180
# Create heatmap for pickup locations
181
pickup_heatmap = gmaps.heatmap_layer(
182
pickup_locations,
183
opacity=0.6,
184
gradient=['blue', 'cyan', 'lime', 'yellow', 'red']
185
)
186
fig.add_layer(pickup_heatmap)
187
188
# Add sample of dropoff locations as markers
189
sample_dropoffs = dropoff_locations.sample(n=min(100, len(dropoff_locations)))
190
dropoff_markers = gmaps.marker_layer(sample_dropoffs)
191
fig.add_layer(dropoff_markers)
192
193
fig
194
195
except Exception as e:
196
print(f"Taxi dataset not available: {e}")
197
```
198
199
### Combining Datasets with Custom Data
200
201
```python
202
import gmaps
203
import gmaps.datasets
204
import pandas as pd
205
import numpy as np
206
207
gmaps.configure(api_key="YOUR_API_KEY")
208
209
# Load built-in earthquake data
210
earthquake_data = gmaps.datasets.load_dataset_as_df('earthquakes')
211
212
# Create synthetic population centers data
213
np.random.seed(42)
214
num_cities = 50
215
city_locations = np.random.uniform(
216
low=[earthquake_data['latitude'].min(), earthquake_data['longitude'].min()],
217
high=[earthquake_data['latitude'].max(), earthquake_data['longitude'].max()],
218
size=(num_cities, 2)
219
)
220
city_populations = np.random.lognormal(mean=10, sigma=1, size=num_cities)
221
222
fig = gmaps.figure()
223
224
# Add earthquake heatmap
225
earthquake_locations = earthquake_data[['latitude', 'longitude']]
226
earthquake_heatmap = gmaps.heatmap_layer(
227
earthquake_locations,
228
opacity=0.4,
229
gradient=['rgba(255,0,0,0)', 'rgba(255,0,0,0.5)', 'rgba(255,0,0,1)']
230
)
231
fig.add_layer(earthquake_heatmap)
232
233
# Add population centers as symbols
234
population_symbols = gmaps.symbol_layer(
235
city_locations,
236
fill_color='blue',
237
scale=[max(1, min(10, pop/10000)) for pop in city_populations],
238
hover_text=[f'Population: {int(pop)}' for pop in city_populations]
239
)
240
fig.add_layer(population_symbols)
241
242
fig
243
```
244
245
### Geographic Analysis with Boundaries
246
247
```python
248
import gmaps
249
import gmaps.geojson_geometries
250
import gmaps.datasets
251
252
gmaps.configure(api_key="YOUR_API_KEY")
253
254
fig = gmaps.figure()
255
256
# Load geographic boundaries
257
try:
258
us_states = gmaps.geojson_geometries.load_geometry('us-states')
259
state_boundaries = gmaps.geojson_layer(
260
us_states,
261
fill_color='none',
262
stroke_color='gray',
263
stroke_weight=1.0
264
)
265
fig.add_layer(state_boundaries)
266
except:
267
print("US states geometry not available")
268
269
# Load and display earthquake data within boundaries
270
earthquake_data = gmaps.datasets.load_dataset_as_df('earthquakes')
271
272
# Filter for US earthquakes (approximate bounds)
273
us_earthquakes = earthquake_data[
274
(earthquake_data['latitude'] >= 25) &
275
(earthquake_data['latitude'] <= 50) &
276
(earthquake_data['longitude'] >= -125) &
277
(earthquake_data['longitude'] <= -65)
278
]
279
280
if not us_earthquakes.empty:
281
us_locations = us_earthquakes[['latitude', 'longitude']]
282
us_magnitudes = us_earthquakes['magnitude']
283
284
earthquake_heatmap = gmaps.heatmap_layer(
285
us_locations,
286
weights=us_magnitudes,
287
opacity=0.6
288
)
289
fig.add_layer(earthquake_heatmap)
290
291
fig
292
```
293
294
### Dataset Exploration and Visualization
295
296
```python
297
import gmaps
298
import gmaps.datasets
299
import pandas as pd
300
301
gmaps.configure(api_key="YOUR_API_KEY")
302
303
# Explore all available datasets
304
datasets = gmaps.datasets.list_datasets()
305
print(f"Found {len(datasets)} datasets:")
306
307
for dataset_name in datasets:
308
try:
309
# Get metadata
310
metadata = gmaps.datasets.dataset_metadata(dataset_name)
311
print(f"\nDataset: {dataset_name}")
312
print(f"Description: {metadata.get('description', 'No description')}")
313
314
# Load a sample
315
data = gmaps.datasets.load_dataset_as_df(dataset_name)
316
print(f"Records: {len(data)}")
317
print(f"Columns: {list(data.columns)}")
318
319
# Try to create a visualization if location columns exist
320
location_cols = [col for col in data.columns if 'lat' in col.lower() or 'lng' in col.lower() or 'lon' in col.lower()]
321
322
if len(location_cols) >= 2:
323
print(f"Creating visualization for {dataset_name}...")
324
fig = gmaps.figure()
325
326
# Assume first two location columns are lat/lng
327
locations = data[location_cols[:2]]
328
329
# Use weights if magnitude/weight column exists
330
weight_cols = [col for col in data.columns if any(term in col.lower() for term in ['mag', 'weight', 'intensity', 'value'])]
331
332
if weight_cols:
333
weights = data[weight_cols[0]]
334
layer = gmaps.heatmap_layer(locations, weights=weights)
335
else:
336
layer = gmaps.heatmap_layer(locations)
337
338
fig.add_layer(layer)
339
# fig # Uncomment to display
340
341
except Exception as e:
342
print(f"Error with dataset {dataset_name}: {e}")
343
```
344
345
### Custom Dataset Integration
346
347
```python
348
import gmaps
349
import gmaps.datasets
350
import pandas as pd
351
352
gmaps.configure(api_key="YOUR_API_KEY")
353
354
# Load built-in data as reference
355
reference_data = gmaps.datasets.load_dataset_as_df('earthquakes')
356
357
# Create custom dataset with similar structure
358
custom_data = pd.DataFrame({
359
'latitude': [37.7749, 34.0522, 40.7128, 41.8781, 29.7604],
360
'longitude': [-122.4194, -118.2437, -74.0060, -87.6298, -95.3698],
361
'magnitude': [5.2, 4.8, 3.1, 4.5, 5.9],
362
'location': ['San Francisco', 'Los Angeles', 'New York', 'Chicago', 'Houston']
363
})
364
365
fig = gmaps.figure()
366
367
# Display reference earthquakes as heatmap
368
ref_locations = reference_data[['latitude', 'longitude']]
369
ref_heatmap = gmaps.heatmap_layer(ref_locations, opacity=0.3)
370
fig.add_layer(ref_heatmap)
371
372
# Display custom data as symbols
373
custom_locations = custom_data[['latitude', 'longitude']]
374
custom_symbols = gmaps.symbol_layer(
375
custom_locations,
376
fill_color='red',
377
scale=custom_data['magnitude'],
378
hover_text=custom_data['location']
379
)
380
fig.add_layer(custom_symbols)
381
382
fig
383
```