CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/pypi-gmaps

Google maps plugin for Jupyter notebooks with interactive visualization capabilities

Pending
Overview
Eval results
Files

datasets.mddocs/

Built-in Datasets and Geometries

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.

Capabilities

Dataset Functions

Access and load curated datasets for common visualization scenarios.

def gmaps.datasets.list_datasets():
    """
    List available built-in datasets.

    Returns:
    list: List of dataset names
    """

def gmaps.datasets.dataset_metadata(dataset_name):
    """
    Get metadata for a dataset.

    Parameters:
    - dataset_name (str): Name of the dataset

    Returns:
    dict: Dictionary with dataset information including description, size, and columns
    """

def gmaps.datasets.load_dataset(dataset_name):
    """
    Load a dataset as list of tuples.

    Parameters:
    - dataset_name (str): Name of the dataset to load

    Returns:
    list: List of data tuples
    """

def gmaps.datasets.load_dataset_as_df(dataset_name):
    """
    Load a dataset as pandas DataFrame.

    Parameters:
    - dataset_name (str): Name of the dataset to load

    Returns:
    pandas.DataFrame: Dataset as DataFrame with proper column names
    """

GeoJSON Geometry Functions

Access built-in GeoJSON geometries for geographic boundaries and regions.

def gmaps.geojson_geometries.list_geometries():
    """
    List available built-in geometries.

    Returns:
    list: List of geometry names
    """

def gmaps.geojson_geometries.geometry_metadata(geometry_name):
    """
    Get metadata for a geometry.

    Parameters:
    - geometry_name (str): Name of the geometry

    Returns:
    dict: Dictionary with geometry information including description and feature count
    """

def gmaps.geojson_geometries.load_geometry(geometry_name):
    """
    Load a GeoJSON geometry.

    Parameters:
    - geometry_name (str): Name of the geometry to load

    Returns:
    dict: GeoJSON geometry dictionary (FeatureCollection)
    """

Usage Examples

Exploring Available Datasets

import gmaps.datasets

# List all available datasets
datasets = gmaps.datasets.list_datasets()
print("Available datasets:", datasets)

# Get metadata for a specific dataset
if 'earthquakes' in datasets:
    metadata = gmaps.datasets.dataset_metadata('earthquakes')
    print("Earthquake dataset metadata:", metadata)

Loading and Using Earthquake Data

import gmaps
import gmaps.datasets

gmaps.configure(api_key="YOUR_API_KEY")

# Load earthquake dataset
earthquake_data = gmaps.datasets.load_dataset_as_df('earthquakes')
print(f"Loaded {len(earthquake_data)} earthquake records")
print("Columns:", earthquake_data.columns.tolist())

# Extract locations and magnitudes
locations = earthquake_data[['latitude', 'longitude']]
magnitudes = earthquake_data['magnitude']

# Create heatmap visualization
fig = gmaps.figure()
heatmap_layer = gmaps.heatmap_layer(
    locations, 
    weights=magnitudes,
    max_intensity=8.0
)
fig.add_layer(heatmap_layer)
fig

Using Built-in Geometries

import gmaps
import gmaps.geojson_geometries

gmaps.configure(api_key="YOUR_API_KEY")

# List available geometries
geometries = gmaps.geojson_geometries.list_geometries()
print("Available geometries:", geometries)

# Load country boundaries
if 'countries' in geometries:
    countries = gmaps.geojson_geometries.load_geometry('countries')
    
    # Create GeoJSON layer
    fig = gmaps.figure()
    geojson_layer = gmaps.geojson_layer(
        countries,
        fill_color='lightblue',
        fill_opacity=0.4,
        stroke_color='blue'
    )
    fig.add_layer(geojson_layer)
    fig

Taxi Ride Analysis

import gmaps
import gmaps.datasets

gmaps.configure(api_key="YOUR_API_KEY")

# Load taxi ride data (if available)
try:
    taxi_data = gmaps.datasets.load_dataset_as_df('taxi_rides')
    
    # Extract pickup and dropoff locations
    pickup_locations = taxi_data[['pickup_latitude', 'pickup_longitude']]
    dropoff_locations = taxi_data[['dropoff_latitude', 'dropoff_longitude']]
    
    fig = gmaps.figure()
    
    # Create heatmap for pickup locations
    pickup_heatmap = gmaps.heatmap_layer(
        pickup_locations,
        opacity=0.6,
        gradient=['blue', 'cyan', 'lime', 'yellow', 'red']
    )
    fig.add_layer(pickup_heatmap)
    
    # Add sample of dropoff locations as markers
    sample_dropoffs = dropoff_locations.sample(n=min(100, len(dropoff_locations)))
    dropoff_markers = gmaps.marker_layer(sample_dropoffs)
    fig.add_layer(dropoff_markers)
    
    fig
    
except Exception as e:
    print(f"Taxi dataset not available: {e}")

Combining Datasets with Custom Data

import gmaps
import gmaps.datasets
import pandas as pd
import numpy as np

gmaps.configure(api_key="YOUR_API_KEY")

# Load built-in earthquake data
earthquake_data = gmaps.datasets.load_dataset_as_df('earthquakes')

# Create synthetic population centers data
np.random.seed(42)
num_cities = 50
city_locations = np.random.uniform(
    low=[earthquake_data['latitude'].min(), earthquake_data['longitude'].min()],
    high=[earthquake_data['latitude'].max(), earthquake_data['longitude'].max()],
    size=(num_cities, 2)
)
city_populations = np.random.lognormal(mean=10, sigma=1, size=num_cities)

fig = gmaps.figure()

# Add earthquake heatmap
earthquake_locations = earthquake_data[['latitude', 'longitude']]
earthquake_heatmap = gmaps.heatmap_layer(
    earthquake_locations,
    opacity=0.4,
    gradient=['rgba(255,0,0,0)', 'rgba(255,0,0,0.5)', 'rgba(255,0,0,1)']
)
fig.add_layer(earthquake_heatmap)

# Add population centers as symbols
population_symbols = gmaps.symbol_layer(
    city_locations,
    fill_color='blue',
    scale=[max(1, min(10, pop/10000)) for pop in city_populations],
    hover_text=[f'Population: {int(pop)}' for pop in city_populations]
)
fig.add_layer(population_symbols)

fig

Geographic Analysis with Boundaries

import gmaps
import gmaps.geojson_geometries
import gmaps.datasets

gmaps.configure(api_key="YOUR_API_KEY")

fig = gmaps.figure()

# Load geographic boundaries
try:
    us_states = gmaps.geojson_geometries.load_geometry('us-states')
    state_boundaries = gmaps.geojson_layer(
        us_states,
        fill_color='none',
        stroke_color='gray',
        stroke_weight=1.0
    )
    fig.add_layer(state_boundaries)
except:
    print("US states geometry not available")

# Load and display earthquake data within boundaries
earthquake_data = gmaps.datasets.load_dataset_as_df('earthquakes')

# Filter for US earthquakes (approximate bounds)
us_earthquakes = earthquake_data[
    (earthquake_data['latitude'] >= 25) & 
    (earthquake_data['latitude'] <= 50) &
    (earthquake_data['longitude'] >= -125) & 
    (earthquake_data['longitude'] <= -65)
]

if not us_earthquakes.empty:
    us_locations = us_earthquakes[['latitude', 'longitude']]
    us_magnitudes = us_earthquakes['magnitude']
    
    earthquake_heatmap = gmaps.heatmap_layer(
        us_locations,
        weights=us_magnitudes,
        opacity=0.6
    )
    fig.add_layer(earthquake_heatmap)

fig

Dataset Exploration and Visualization

import gmaps
import gmaps.datasets
import pandas as pd

gmaps.configure(api_key="YOUR_API_KEY")

# Explore all available datasets
datasets = gmaps.datasets.list_datasets()
print(f"Found {len(datasets)} datasets:")

for dataset_name in datasets:
    try:
        # Get metadata
        metadata = gmaps.datasets.dataset_metadata(dataset_name)
        print(f"\nDataset: {dataset_name}")
        print(f"Description: {metadata.get('description', 'No description')}")
        
        # Load a sample
        data = gmaps.datasets.load_dataset_as_df(dataset_name)
        print(f"Records: {len(data)}")
        print(f"Columns: {list(data.columns)}")
        
        # Try to create a visualization if location columns exist
        location_cols = [col for col in data.columns if 'lat' in col.lower() or 'lng' in col.lower() or 'lon' in col.lower()]
        
        if len(location_cols) >= 2:
            print(f"Creating visualization for {dataset_name}...")
            fig = gmaps.figure()
            
            # Assume first two location columns are lat/lng
            locations = data[location_cols[:2]]
            
            # Use weights if magnitude/weight column exists
            weight_cols = [col for col in data.columns if any(term in col.lower() for term in ['mag', 'weight', 'intensity', 'value'])]
            
            if weight_cols:
                weights = data[weight_cols[0]]
                layer = gmaps.heatmap_layer(locations, weights=weights)
            else:
                layer = gmaps.heatmap_layer(locations)
            
            fig.add_layer(layer)
            # fig  # Uncomment to display
            
    except Exception as e:
        print(f"Error with dataset {dataset_name}: {e}")

Custom Dataset Integration

import gmaps
import gmaps.datasets
import pandas as pd

gmaps.configure(api_key="YOUR_API_KEY")

# Load built-in data as reference
reference_data = gmaps.datasets.load_dataset_as_df('earthquakes')

# Create custom dataset with similar structure
custom_data = pd.DataFrame({
    'latitude': [37.7749, 34.0522, 40.7128, 41.8781, 29.7604],
    'longitude': [-122.4194, -118.2437, -74.0060, -87.6298, -95.3698],
    'magnitude': [5.2, 4.8, 3.1, 4.5, 5.9],
    'location': ['San Francisco', 'Los Angeles', 'New York', 'Chicago', 'Houston']
})

fig = gmaps.figure()

# Display reference earthquakes as heatmap
ref_locations = reference_data[['latitude', 'longitude']]
ref_heatmap = gmaps.heatmap_layer(ref_locations, opacity=0.3)
fig.add_layer(ref_heatmap)

# Display custom data as symbols
custom_locations = custom_data[['latitude', 'longitude']]
custom_symbols = gmaps.symbol_layer(
    custom_locations,
    fill_color='red',
    scale=custom_data['magnitude'],
    hover_text=custom_data['location']
)
fig.add_layer(custom_symbols)

fig

Install with Tessl CLI

npx tessl i tessl/pypi-gmaps

docs

datasets.md

directions.md

drawing.md

figure-map.md

geojson.md

heatmap.md

index.md

markers.md

transportation.md

tile.json