or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

datasets.mddirections.mddrawing.mdfigure-map.mdgeojson.mdheatmap.mdindex.mdmarkers.mdtransportation.md
tile.json

tessl/pypi-gmaps

Google maps plugin for Jupyter notebooks with interactive visualization capabilities

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
pypipkg:pypi/gmaps@0.9.x

To install, run

npx @tessl/cli install tessl/pypi-gmaps@0.9.0

index.mddocs/

gmaps

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.

Package Information

  • Package Name: gmaps
  • Package Type: pypi
  • Language: Python
  • Installation: pip install gmaps

Core Imports

import gmaps

Common for working with maps:

import gmaps
gmaps.configure(api_key="YOUR_API_KEY")

Basic Usage

import gmaps
import gmaps.datasets

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

# Create a figure
fig = gmaps.figure()

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

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

# Display the map
fig

Architecture

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

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

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

Capabilities

Figure and Map Management

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

def configure(api_key=None): ...
def figure(display_toolbar=True, display_errors=True, zoom_level=None, tilt=45, center=None, layout=None, map_type='ROADMAP', mouse_handling='COOPERATIVE'): ...

class Figure:
    def add_layer(self, layer): ...

class Map:
    def add_layer(self, layer): ...

Figure and Map Management

Heatmap Visualization

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

def heatmap_layer(locations, weights=None, max_intensity=None, dissipating=True, point_radius=None, opacity=0.6, gradient=None): ...

class Heatmap:
    locations: list
    max_intensity: float
    point_radius: int
    dissipating: bool
    opacity: float
    gradient: list

class WeightedHeatmap:
    locations: list
    weights: list

Heatmap Visualization

Marker and Symbol Layers

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

def marker_layer(locations, hover_text='', label='', info_box_content=None, display_info_box=None): ...
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): ...

class Markers:
    markers: list

class Marker:
    location: tuple
    hover_text: str
    label: str
    display_info_box: bool
    info_box_content: str

class Symbol:
    location: tuple
    fill_color: str
    fill_opacity: float
    stroke_color: str
    stroke_opacity: float
    scale: float

Marker and Symbol Layers

GeoJSON Visualization

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

def geojson_layer(geojson, fill_color=None, fill_opacity=0.4, stroke_color=None, stroke_opacity=1.0, stroke_weight=1.0): ...

class GeoJson:
    features: list

class GeoJsonFeature:
    feature: dict
    fill_color: str
    fill_opacity: float
    stroke_color: str
    stroke_opacity: float
    stroke_weight: float

GeoJSON Visualization

Direction and Route Planning

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

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): ...

class Directions:
    start: tuple
    end: tuple
    waypoints: list
    travel_mode: str
    avoid_ferries: bool
    avoid_highways: bool
    avoid_tolls: bool
    stroke_color: str
    stroke_weight: float
    stroke_opacity: float

Direction and Route Planning

Interactive Drawing Tools

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

def drawing_layer(features=None, mode='MARKER', show_controls=True, marker_options=None, line_options=None, polygon_options=None, circle_options=None): ...

class Drawing:
    features: list
    mode: str
    show_controls: bool

class Line:
    start: tuple
    end: tuple
    stroke_color: str
    stroke_weight: float
    stroke_opacity: float

class Polygon:
    path: list
    stroke_color: str
    stroke_weight: float
    stroke_opacity: float
    fill_color: str
    fill_opacity: float

class Circle:
    center: tuple
    radius: float
    stroke_color: str
    stroke_weight: float
    stroke_opacity: float
    fill_color: str
    fill_opacity: float

Interactive Drawing Tools

Transportation and Traffic Layers

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

def traffic_layer(auto_refresh=True): ...
def transit_layer(): ...
def bicycling_layer(): ...

class Traffic:
    auto_refresh: bool

class Transit: ...

class Bicycling: ...

Transportation and Traffic Layers

Built-in Datasets and Geometries

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

# Dataset functions
def gmaps.datasets.list_datasets(): ...
def gmaps.datasets.dataset_metadata(dataset_name): ...
def gmaps.datasets.load_dataset(dataset_name): ...
def gmaps.datasets.load_dataset_as_df(dataset_name): ...

# Geometry functions  
def gmaps.geojson_geometries.list_geometries(): ...
def gmaps.geojson_geometries.geometry_metadata(geometry_name): ...
def gmaps.geojson_geometries.load_geometry(geometry_name): ...

Built-in Datasets and Geometries

Common Types

# Location coordinates
LocationType = tuple[float, float]  # (latitude, longitude)

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

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

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

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

# Layout configuration
LayoutType = dict  # Widget layout parameters

Error Handling

class InvalidGeoJson(Exception):
    """Raised when invalid GeoJSON is provided"""

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

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

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