This is the kepler.gl jupyter widget, an advanced geospatial visualization tool, to render large-scale interactive maps in Jupyter Notebook.

• Installation
• Quick Start
• Demo Notebooks
• Usage
• Local Development Setup
• FAQ & Troubleshoot

• Python >= 2
• ipywidgets >= 7.0.0

To install use pip:

$ pip install keplergl

If you on Mac used pip install and running Notebook 5.3 and above, you don't need to run the following

$ jupyter nbextension install --py --sys-prefix keplergl # can be skipped for notebook 5.3 and above

$ jupyter nbextension enable --py --sys-prefix keplergl # can be skipped for notebook 5.3 and above

If you arr in JupyterLab, you will also need to install the JupyterLab extension. This require node > 8.15.0

If you use Homebrew on Mac:

$ brew install node@8

Then install jupyter labextension.

$ jupyter labextension install @jupyter-widgets/jupyterlab-manager keplergl-jupyter

Prerequisites for JupyterLab:

• Node > 8.15.0
• Python 3
• JupyterLab>=1.0.0

# Load kepler.gl with an empty map
from keplergl import KeplerGl
map_1 = KeplerGl(height=400)
map_1

# Load kepler.gl with map data and config
map_2 = KeplerGl(height=400, data={'data_1': df}, config=config)
map_2

# Add data to map
map_1.add_data(df, 'data_1')

# Apply config
map_1.config(config)

# print data and config
map_1.data
map_1.config

# save map to html
map_1.save_to_html(file_name='keplergl_map.html')

• Load kepler.gl: Load kepler.gl widget, add data and config
• Geometry as String: Embed Polygon geometries as GeoJson and WKT inside a CSV
• GeoJSON: Load GeoJSON to kepler.gl
• DataFrame: Load DataFrame to kepler.gl
• GeoDataFrame: Load GeoDataFrame to kepler.gl

• 1. Load kepler.gl
  • keplergl.KeplerGl()
• 2. Add Data
  • .add_data()
  • .data
• 3. Data Format
  • CSV
  • GeoJSON
  • DataFrame
  • GeoDataFrame
  • WKT
• 4. Customize the map
• 5. Save and load config
  • .config
• 6. Match config with data
• 7. Save Map
  • .save_to_html()

You will need to install node, yarn and Jupyter Notebook.

Install node > 8.15.0, and yarn. Use nvm for better node version management e.g. nvm install 8.

Python 3

$ python3 -m pip install --upgrade pip
$ python3 -m pip install jupyter

Python 2

$ python -m pip install --upgrade pip
$ python -m pip install jupyter

$ git clone https://github.com/keplergl/kepler.gl.git

    $ cd bindings/kepler.gl-jupyter
    $ cd js
    $ yarn --ignore-engines

Add Mapbox access token to Node env.

export MapboxAccessTokenJupyter=<your_mapbox_token>

$ npm start

You need to run step 2 and 3 to restart the js program. And step 1-3 if any js dependency has changed (Usually after pulling new changes from master).

This command must be run AFTER the js setup, and folder static/ was created. It only needs to be run once.

    # dev install from folder containing setup.py
    $ pip install -e .

    # only needed in dev mode, not in normal mode.
    $ jupyter nbextension install --py --symlink --sys-prefix keplergl

    # only needed in dev mode, not in normal mode.
    $ jupyter nbextension enable --py --sys-prefix keplergl

$ cd notebooks
$ jupyter notebook

You can now start editing the .js and .py files to see changes reflected in your local notebook. After changing files in the js folder, the local start script will recompile the js files and put them in to keplergl/static folder. You need to reload the jupyter notebook page to reload the files.

keplergl is currently only published to PyPI, and unfortunately I use a Mac. If you encounter errors installing it on windows. This issue might shed some light. Follow this issue for conda support.

Make sure you are using node 8.15.0. and you have installed @jupyter-widgets/jupyterlab-manager. Depends on your JupyterLab version. You might need to install the specific version of jupyterlab-manager. with jupyter labextension install @jupyter-widgets/jupyterlab-manager@0.31. When use it in Jupyter lab, keplergl is only supported in JupyterLab > 1.0 and Python 3.

Run jupyter labextension install keplergl-jupyter --debug and copy console output before creating an issue.

If you are running install and uninstall several times. You should run.

jupyter lab clean
jupyter lab build

If you see this error during install labextension

$ FATAL ERROR: CALL_AND_RETRY_LAST Allocation failed - JavaScript heap out of memory

run

$ export NODE_OPTIONS=--max-old-space-size=4096

Run jupyter labextension list You should see below. (Version may vary)

JupyterLab v1.1.4
Known labextensions:
   app dir: /Users/xxx/jupyter-python3/ENV3/share/jupyter/lab
        @jupyter-widgets/jupyterlab-manager v1.0.2  enabled  OK
        keplergl-jupyter v0.1.0  enabled  OK

Python

python==3.7.4
notebook==6.0.1
jupyterlab==1.1.4
ipywidgets==7.5.1

Node (Only for JupyterLab)

node==8.15.0
yarn==1.7.0