Skip to content
Branch: master
Find file Copy path
Find file Copy path
1 contributor

Users who have contributed to this file

330 lines (252 sloc) 11.9 KB for Jupyter User Guide


pip install keplergl

1. Load keplergl map


  • Input:
    • height optional default: 400

      Height of the map display

    • data dict optional

      Datasets as a dictionary, key is the name of the dataset. Read more on Accepted data format

    • config dict optional Map config as a dictionary. The dataId in the layer and filter settings should match the name of the dataset they are created under

The following command will load widget below a cell. The map object created here is map_1 it will be used throughout the code example in this doc.

# Load an empty map
from keplergl import KeplerGl
map_1 = KeplerGl()

empty map

You can also create the map and pass in the data or data and config at the same time. Follow the instruction to match config with data

# Load a map with data and config and height
from keplergl import KeplerGl
map_2 = KeplerGl(height=400, data={"data_1": my_df}, config=config)

Load map with data and config

2. Add Data


  • Inputs
    • data required CSV, GeoJSON or DataFrame. Read more on Accepted data format
    • name required Name of the data entry.

name of the dataset will be the saved to the dataId property of each layer, filter and interactionConfig in the config. expected the data to be CSV, GeoJSON, DataFrame or GeoDataFrame. You can call add_data multiple times to add multiple datasets to

# DataFrame
df = pd.read_csv('hex-data.csv')
map_1.add_data(data=df, name='data_1')

with open('csv-data.csv', 'r') as f:
    csvData =
map_1.add_data(data=csvData, name='data_2')

# GeoJSON as string
with open('sf_zip_geo.json', 'r') as f:
    geojson =

map_1.add_data(data=geojson, name='geojson')

Add data to map


Print the current data added to the map. As a Dict
# {'data_1': 'hex_id,value\n89283082c2fffff,64\n8928308288fffff,73\n89283082c07ffff,65\n89283082817ffff,74\n89283082c3bffff,66\n8...`,
#  'data_3': 'location, lat, lng, name\n..',
#  'data_3': '{"type": "FeatureCollecti...'}

3. Data Format supports CSV, GeoJSON, Pandas DataFrame or GeoPandas GeoDataFrame.


You can create a CSV string by reading from a CSV file.

with open('csv-data.csv', 'r') as f:
    csvData =
# csvData = "hex_id,value\n89283082c2fffff,64\n8928308288fffff,73\n89283082c07ffff,65\n89283082817ffff,74\n89283082c3bffff,66\n8..."
map_1.add_data(data=csvData, name='data_2')


According to GeoJSON Specification (RFC 7946): GeoJSON is a format for encoding a variety of geographic data structures. A GeoJSON object may represent a region of space (a Geometry), a spatially bounded entity (a Feature), or a list of Features (a FeatureCollection). GeoJSON supports the following geometry types: Point, LineString, Polygon, MultiPoint, MultiLineString, MultiPolygon, and GeometryCollection. Features in GeoJSON contain a Geometry object and additional properties, and a FeatureCollection contains a list of Features. supports all the GeoJSON types above excepts GeometryCollection. You can pass in either a single Feature or a FeatureCollection. You can format the GeoJSON either as a string or a dict type

feature = {
    "type": "Feature",
    "properties": {"name": "Coors Field"},
    "geometry": {"type": "Point", "coordinates": [-104.99404, 39.75621]}

featureCollection = {
    "type": "FeatureCollection",
    "features": [{
        "type": "Feature",
        "geometry": {"type": "Point", "coordinates": [102.0, 0.5]},
        "properties": {"prop0": "value0"}

map_1.add_data(data=feature, name="feature")
map_1.add_data(data=featureCollection, name="feature_collection")

Geometries (Polygons, LindStrings) can be embedded into CSV or DataFrame with a GeoJSON Json string. Use the geometry property of a Feature, which includes type and coordinates.

# GeoJson Feature geometry
geometryString = {
    'type': 'Polygon',
    'coordinates': [[[-74.158491,40.835947],[-74.148473,40.834522],[-74.142598,40.833128],[-74.151923,40.832074],[-74.158491,40.835947]]]

# create json string
json_str = json.dumps(geometryString)

# create data frame
df_with_geometry = pd.DataFrame({
    'id': [1],
    'geometry_string': [json_str]

# add to map
map_1.add_data(df_with_geometry, "df_with_geometry")

DataFrame accepts pandas.DataFrame

df = pd.DataFrame(
    {'City': ['Buenos Aires', 'Brasilia', 'Santiago', 'Bogota', 'Caracas'],
     'Latitude': [-34.58, -15.78, -33.45, 4.60, 10.48],
     'Longitude': [-58.66, -47.91, -70.66, -74.08, -66.86]})

w1.add_data(data=df, name='cities')

GeoDataFrame accepts geopandas.GeoDataFrame, it automatically converts the current geometry column from shapely to wkt string.

url = ''
country_gdf = geopandas.read_file(url)
w1.add_data(data=country_gdf, name="state")

US state


You can embed geometries (Polygon, LineStrings etc) into CSV or DataFrame using WKT

wkt_str = 'POLYGON ((-74.158491 40.835947, -74.130031 40.819962, -74.148818 40.830916, -74.151923 40.832074, -74.158491 40.835947))'

df_w_wkt = pd.DataFrame({
    'id': [1],
    'wkt_string': [wkt_str]

map_1.add_data(df_w_wkt, "df_w_wkt")

4. Customize the map

Interact with and customize layers and filters. Map data and config will be stored locally to the widget state. To make sure the map state is saved, select Widgets > Save Notebook Widget State, before shutting down the kernel.

Map interaction

5. Save and load config


you can print your current map configuration at any time.

## {u'config': {u'mapState': {u'bearing': 2.6192893401015205,
#  u'dragRotate': True,
#   u'isSplit': False,
#   u'latitude': 37.76209132041332,
#   u'longitude': -122.42590232651203,

When the map is final, you can copy this config and load it later to reproduce the same map. Follow the instruction to match config with data. There are 2 ways to apply config to a map:

  1. Directly apply config to the map.
config = {
    'version': 'v1',
    'config': {
        'mapState': {
            'latitude': 37.76209132041332,
            'longitude': -122.42590232651203,
            'zoom': 12.32053899007826
map_1.add_data(data=df, name='data_1')
map_1.config = config
  1. Load it when creating the map
map_1 = KeplerGl(height=400, data={'data_1': my_df}, config=config)

If want to load the map next time with this saved config, the easiest way to do is to save the it to a file and use the magic command %run to load it w/o cluttering up your notebook.

# Save map_1 config to a file
with open('', 'w') as f:
   f.write('config = {}'.format(map_1.config))

# load the config

6. Match config with data

All layers, filters and tooltips are associated with a specific dataset. Therefore the data and config in the map has to be able to match each other. The name of the dataset is assigned to:

  • dataId of layer.config,
  • dataId of filter
  • key in interactionConfig.tooltip.fieldToShow.

Connect data and config

You can use the same config on another dataset with the same name and schema.

7. Save Map

When you click in the map and change settings, config is saved to widget state. Closing the notebook and reopen it will reload current map. However, you need to manually select Widget > Save Notebook Widget State before shut downing the kernel to make sure it will be reloaded.

Save Widget State


  • input
    • data: optional A data dictionary {"name": data}, if not provided, will use current map data
    • config: optional map config dictionary, if not provided, will use current map config
    • file_name: optional the html file name, default is keplergl_map.html
    • read_only: optional if read_only is True, hide side panel to disable map customization

You can export your current map as an interactive html file.

# this will save current map

# this will save map with provided data and config
map_1.save_to_html(data={'data_1': df}, config=config, file_name='first_map.html')

# this will save map with the interaction panel disabled
map_1.save_to_html(file_name='first_map.html' read_only=True)

Demo Notebooks

You can’t perform that action at this time.