Kepler.gl

Create Maps with keplergl

Use the keplergl Python package to create standalone, interactive HTML map files from geospatial data. The exported HTML loads kepler.gl from CDN — no JavaScript build or server is needed. The resulting .html file can be opened directly in any browser.

Installation

pip install keplergl

Requires keplergl >= 0.4.0. Earlier versions use a different widget/serialization API and the examples in this skill will not work. Requirements: Python >= 3.9. Dependencies (pandas, geopandas, shapely) are installed automatically.

Instructions

1. Import KeplerGl from keplergl
2. Load data as a DataFrame, GeoDataFrame, GeoJSON dict, or CSV string
3. Create a map with KeplerGl(data={'name': data_object})
4. Optionally configure layers, colors, and map state via a config dict (default to quantile color scale and a vibrant palette for quantitative color encoding when the user does not specify)
5. Export with map.save_to_html(file_name='output.html', center_map=True)
6. The output HTML is fully standalone — open it in any browser

API Reference

KeplerGl(data=None, config=None, height=400, mapbox_token="", use_arrow=False, show_docs=False, theme="", app_name="kepler.gl", **kwargs)

.add_data(data, name="data", use_arrow=None)

• data: DataFrame, GeoDataFrame, CSV string, GeoJSON dict, or GeoJSON string
• name: Dataset identifier (default: "data") — must match dataId in config if using a config
• use_arrow: If True, serialize this DataFrame as Arrow IPC. If None (default), falls back to the widget-level use_arrow setting. Has no effect on GeoDataFrames.

.save_to_html(file_name="keplergl_map.html", data=None, config=None, read_only=False, center_map=True, mapbox_token="", json_encoder=str, app_name=None, theme=None)

.config

Read or set the map configuration dict. Use map.config after customizing in Jupyter UI, then save and reuse.

Key Rules

• dataId must match the dataset name — every layer and filter references a dataset by dataId; this must match the key in the data dict or the name passed to add_data().
• GeoJSON columns use _geojson — when data is loaded as GeoJSON, the geometry column is internally named _geojson in configs.
• colorField / colorScale / sizeField / heightField etc. belong under visualChannels, NOT under config. Putting them under config is silently ignored — the layer will render but the "Color Based On (field)" input shows empty. The layer object must have two siblings: config (for dataId, columns, visConfig, …) and visualChannels (for all field-to-channel mappings).
• Columns named latitude/lat/lng/longitude are auto-detected as coordinates.
• H3 hex IDs are auto-detected if a column contains valid H3 strings.
• Use center_map=True to auto-fit map bounds. Use read_only=True to hide the side panel.
• For numeric color encoding, if the user does not specify a color scale, use visualChannels.colorScale: 'quantile'.
• For numeric color encoding, if the user does not specify a palette, use a vibrant sequential/diverging palette (for example, colorRange.name: 'Global Warming').
• If the user asks for custom class breaks, compute breakpoints in Python first (for example with pygeoda), add a derived classified/bin column to the dataset, and map colors using that derived field.
• No SampleMapPanel in standalone exports. The SampleMapPanel React component lives in the kepler.gl demo app, not in the UMD bundle used by save_to_html(). To show a summary/legend overlay, inject an HTML+CSS <div> into the exported file (position it at right: 56px or left: 66px so it doesn't block map controls). See Summary Panel Overlay.

Supported Data Formats

Layer Types

Config Structure

config = {
    'version': 'v1',
    'config': {
        'visState': {
            'layers': [...],          # Layer definitions
            'filters': [...],         # Data filters
            'interactionConfig': {},  # Tooltips, brush, geocoder
            'splitMaps': [],          # Split map views
            'layerBlending': 'normal' # 'normal', 'additive', 'subtractive'
        },
        'mapState': {
            'latitude': 37.76,
            'longitude': -122.4,
            'zoom': 11,
            'bearing': 0,
            'pitch': 0,
            'dragRotate': False,
            'isSplit': False
        },
        'mapStyle': {
            'styleType': 'dark-matter'
        }
    }
}

Basemap Styles

Free (no token needed): dark-matter, positron, voyager, dark-matter-nolabels, positron-nolabels, voyager-nolabels

Mapbox (require mapbox_token): dark, light, muted, muted_night

Additional Resources

For detailed per-layer-type examples with full config, see supporting files:

• Point Map — Scatter plot from lat/lng
• GeoJSON / Polygon Map — Polygons, lines from GeoJSON or GeoDataFrame
• H3 Hexagon Map — H3 spatial index hexagons
• Arc / Line Map — Origin-destination connections
• Heatmap — Density heatmap from points
• Hexbin Aggregation Map — Spatial binning into hexagons
• Trip Animation Map — Animated trips along paths
• Summary Panel Overlay — Inject a SampleMapPanel-style info overlay into the exported HTML (for LISA/cluster counts, model summaries, custom legends)

Examples

For full config examples per layer type, see:

• Point Map — includes quantile color + vibrant palette config
• GeoJSON / Polygon Map — includes choropleth config with visualChannels

Quick start (auto-detected layers, no config needed)

from keplergl import KeplerGl
import pandas as pd

df = pd.DataFrame({
    'lat': [37.7749, 34.0522, 40.7128],
    'lng': [-122.4194, -118.2437, -74.0060],
    'name': ['San Francisco', 'Los Angeles', 'New York'],
    'value': [15, 42, 27]
})

map_1 = KeplerGl(data={'cities': df})
map_1.save_to_html(file_name='cities_map.html', center_map=True)

GeoDataFrame from shapefile

from keplergl import KeplerGl
import geopandas as gpd

gdf = gpd.read_file('shapefile.shp')
map_1 = KeplerGl(data={'regions': gdf})
map_1.save_to_html(file_name='regions_map.html', read_only=True, center_map=True)

Multiple datasets

map_1 = KeplerGl(data={
    'locations': points_df,
    'routes': routes_df
})
map_1.save_to_html(file_name='combined_map.html', center_map=True)

Save and reuse config

import json
# Save
with open('my_config.json', 'w') as f:
    json.dump(map_1.config, f)
# Load
with open('my_config.json', 'r') as f:
    config = json.load(f)
map_2 = KeplerGl(data={'data_1': df}, config=config)
map_2.save_to_html(file_name='map.html')