Kepler.gl Visualization — Core Concepts

Kepler.gl is a GPU-accelerated geospatial visualization tool developed by Uber. The Python package keplergl embeds it inside Jupyter notebooks, letting you build interactive maps from Pandas DataFrames or GeoDataFrames without writing JavaScript.

Quick start

from keplergl import KeplerGl
import pandas as pd

df = pd.read_csv("taxi_trips.csv")
# Columns: pickup_lat, pickup_lng, dropoff_lat, dropoff_lng, fare

map1 = KeplerGl(height=600)
map1.add_data(data=df, name="taxi_trips")
map1

A full interactive map renders in the notebook cell. Click and drag to pan, scroll to zoom, and use the sidebar to configure layers.

Layer types

Kepler.gl supports several visualization layers out of the box:

Layer	Best for	Data requirement
Point	Individual locations	lat/lng columns
Arc	Origin-destination flows	start lat/lng + end lat/lng
Line	Connections, routes	start lat/lng + end lat/lng
Heatmap	Density patterns	lat/lng columns
Hexbin	Aggregated counts in hex tiles	lat/lng columns
Grid	Square-grid aggregation	lat/lng columns
Polygon	Boundaries, zones	GeoJSON geometry
3D Column	Aggregated values with height	lat/lng + value column
Trip	Animated trajectories	GeoJSON LineString + timestamps

Most layers auto-detect from your data schema. You can also manually configure them through the sidebar or programmatically.

Adding GeoDataFrame data

import geopandas as gpd

buildings = gpd.read_file("buildings.geojson")
map1.add_data(data=buildings, name="buildings")

Kepler.gl renders polygon geometries natively, coloring and extruding them based on attribute columns.

Programmatic configuration

Every visual setting can be controlled via a JSON config dict:

config = {
    "version": "v1",
    "config": {
        "mapState": {
            "latitude": 40.748,
            "longitude": -73.985,
            "zoom": 12,
            "pitch": 45,
            "bearing": 0,
        },
        "visState": {
            "layers": [
                {
                    "type": "point",
                    "config": {
                        "dataId": "taxi_trips",
                        "columns": {"lat": "pickup_lat", "lng": "pickup_lng"},
                        "color": [255, 153, 31],
                        "visConfig": {"radius": 5, "opacity": 0.8},
                    },
                }
            ]
        },
    },
}

map2 = KeplerGl(height=600, data={"taxi_trips": df}, config=config)

Saving and loading configs

# Export current config (after adjusting in the UI)
saved_config = map1.config

# Reuse on new data
map3 = KeplerGl(height=600, data={"new_data": df2}, config=saved_config)

This lets you create a visual style once and reapply it across datasets.

Filtering data

The time filter is one of Kepler.gl’s most powerful features. If your data has a timestamp column, Kepler shows a time slider that animates the data over time — perfect for visualizing rush-hour patterns or event propagation.

# Ensure timestamps are in a format Kepler recognizes
df["pickup_time"] = pd.to_datetime(df["pickup_time"])
map1.add_data(data=df, name="trips")
# Then enable the time filter in the sidebar

Exporting maps

# Save as an interactive HTML file (no server needed)
map1.save_to_html(file_name="taxi_map.html")

The HTML file is self-contained — it includes the data and Kepler.gl JavaScript bundle. Share it with anyone who has a web browser.

Common misconception

People often assume Kepler.gl is just for points on a map. Its real strength is aggregation — hexbin layers, heatmaps, and 3D columns reveal density patterns that individual points obscure. A million scattered dots are noise; a hexbin grid with height encoding is insight.

The one thing to remember: Kepler.gl bridges the gap between raw location data and visual insight — its GPU-powered layers handle millions of points, and its interactive sidebar lets you explore patterns without writing configuration code.