Create interactive map visualizations and export to standalone HTML using the keplergl Python package. Use when the user wants to create maps, visualize geospatial data, plot locations on a map, or generate HTML map files from DataFrames, GeoDataFrames, GeoJSON, or CSV data with coordinates.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
A direct command skips the review prompt. Inspect the source before running it.
Create interactive map visualizations and export to standalone HTML using the keplergl Python package. Use when the user wants to create maps, visualize geospatial data, plot locations on a map, or generate HTML map files from DataFrames, GeoDataFrames, GeoJSON, or CSV data with coordinates.
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
Import KeplerGl from keplergl
Load data as a DataFrame, GeoDataFrame, GeoJSON dict, or CSV string
Create a map with KeplerGl(data={'name': data_object})
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)
Export with map.save_to_html(file_name='output.html', center_map=True)
The output HTML is fully standalone — open it in any browser
Serialize DataFrames as Arrow IPC (more compact, preserves types)
show_docs
bool
False
Deprecated (kept for compatibility)
theme
str
""
"light", "dark", "base", or "" (default dark)
app_name
str
"kepler.gl"
App name in header and HTML title
.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.
Data override for export (uses current widget data when None)
config
dict
None
Config override for export (uses current widget config when None)
read_only
bool
False
True = hide side panel
center_map
bool
True
True = auto-fit map to data bounds
mapbox_token
str
""
Mapbox token override for export
json_encoder
callable
str
Fallback encoder for non-JSON-native values in GeoDataFrames
app_name
str
None
App name override for export title/header
theme
str
None
Theme override for export ("light", "dark", "base", or "")
.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
Format
How to Load
pandas DataFrame
Columns with lat/lng (or similar) for point data
geopandas GeoDataFrame
Geometry column auto-detected. Interactive widget serialization uses GeoArrow (no CRS reprojection); HTML export path re-projects to EPSG:4326 when needed.
CSV string
Raw CSV text with lat/lng or geometry columns
GeoJSON dict
Feature or FeatureCollection as Python dict
GeoJSON string
JSON string of GeoJSON
WKT in DataFrame
DataFrame column containing WKT geometry strings
Layer Types
Layer Type
Config type
Typical Data
Point
"point"
DataFrame with lat/lng columns
Arc
"arc"
DataFrame with origin/destination lat/lng
Line
"line"
DataFrame with origin/destination lat/lng
Hexbin
"hexagon"
DataFrame with lat/lng (aggregated spatially)
Heatmap
"heatmap"
DataFrame with lat/lng
H3 Hexagon
"hexagonId"
DataFrame with H3 hex ID column
GeoJSON / Polygon
"geojson"
GeoJSON or GeoDataFrame with polygon/line geometries
