Repository files navigation

A CLI and Python API for quickly viewing geospatial data in Kepler.gl.

Uber's open-sourcekepler.gl is a great browser-basedplatform for interactively visualizing geospatial data. Thekeplergl Python package'sincludeddocumentationis almost entirely directed at use within Jupyter, and it took a little bit ofwork to figure out how to use it from a non-Jupyter Python environment.

This package is a simple wrapper to quickly get your data into kepler.gl. Fromthe command line, it's as simple as:

export MAPBOX_API_KEY=...keplergl data1.geojson data2.shp data3.gdbcat data.geojson | keplergl

from Python:

fromkeplergl_cliimportVisualizeVisualize(data)

• One-line data visualization
• Automatically converts Shapely objects to GeoJSON
• Supports piped GeoJSON input
• No configuration needed

Mapbox API key: in order to display Mapbox-hosted maps, you need to providea Mapbox API key. Go toMapbox.comto get an API key.

Package install:

pip install keplergl_cli

This package has dependencies ongeojson,shapely, andgeopandas. If youget errors when installing this package through pip, it may be easier to firstinstall dependencies through Conda, then install this package. I.e.:

conda install geojson shapely geopandas -c conda-forgepip install keplergl_cli

The CLI is installed under the namekepler:

export MAPBOX_API_KEY=...kepler --style=outdoors data.geojsonkepler --style=dark data1.geojson shapefile.shp geodatabase.gdb -l layer1 -l layer2cat data.geojson | kepler

You can addexport MAPBOX_API_KEY to your.bashrc or.zshrc to not have torun that step each time.

You can supply filename paths to data in anyvector format readable byGeoPandas/GDAL. Alternatively youcan supply GeoJSON or newline-delimited GeoJSON on stdin.

Supply--help to see the CLI's help menu:

> kepler --helpUsage: kepler [OPTIONS] FILES...  Interactively view geospatial data using kepler.glOptions:  -l, --layer TEXT  Layer names. If not provided, will display all layers  --api_key TEXT    Mapbox API Key. Must be provided on the command line or                    exist in the MAPBOX_API_KEY environment variable.  --style TEXT      Mapbox style. Accepted values are: streets, outdoors,                    light, dark, satellite, satellite-streets, or a custom                    style URL.  [default: streets]  --help            Show this message and exit.

Simplest usage:

importgeopandasasgpdfromkeplergl_cliimportVisualize# Create your geospatial objectsgdf=gpd.GeoDataFrame(...)# Visualize one or multiple objects at a timeVisualize(gdf,api_key=MAPBOX_API_KEY)Visualize([gdf,shapely_object,geojson_string],api_key=MAPBOX_API_KEY)

More detail over the objects in your map:

fromkeplergl_cliimportVisualizevis=Visualize(api_key=MAPBOX_API_KEY)vis.add_data(data=data,names='name of layer')vis.add_data(data=data2,names='name of layer')html_path=vis.render(open_browser=True,read_only=False)

Visualize

Visualize(data=None,names=None,read_only=False,api_key=None,style=None)

• data (eitherNone, a single data object, or a list of data objects):

  A data object may be a GeoDataFrame from theGeoPandas library, any geometry from theShapely library, anyobject from theGeoJSON library, orany GeoJSONstr ordict. You can also provide a CSV file as astring or a Pandas DataFrame if the DataFrame hasLatitude andLongitudecolumns. Full documentation on the accepted data formats ishere.

  You can provide either a single data object, or an iterable containingmultiple allowed data objects.

  If data is notNone, then Visualize(data) will perform all steps, includingrendering the data to an HTML file and opening it in a new browser tab.

• names (eitherNone, a string, or a list of strings):

  This defines the names shown for each layer in Kepler.gl. IfNone, thelayers will be nameddata_0,data_1, and so on. Otherwise, ifdata isa single object,names should be a string, and ifdata is an iterable,thennames should be an iterable of strings.

• read_only (boolean): IfTrue, hides side panel to disable map customization

• api_key (string): Mapbox API key. Go toMapbox.comto get an API key. If not provided, theMAPBOX_API_KEY environmentvariable must be set, or thestyle_url must point to astyle.json filethat does not use Mapbox map tiles.

• style (string): The basemap style to use. Standard Mapbox options are:

  • streets
  • outdoors
  • light
  • dark
  • satellite
  • satellite-streets

  The default isstreets. Alternatively, you can supply a path to a customstyle. A custom style created from Mapbox Studio should have a url thatstarts withmapbox://. Otherwise, a custom style using third-party maptiles should be a URL to a JSON file that conforms to theMapbox StyleSpecification.

Visualize.add_data()

Visualize.add_data(data,names=None):

• data (either a single data object, or a list of data objects):

  A data object may be a GeoDataFrame from theGeoPandas library, any geometry from theShapely library, anyobject from theGeoJSON library, orany GeoJSON string or dictionary. You can also provide a CSV file as astring or a Pandas DataFrame if the DataFrame hasLatitude andLongitudecolumns. Full documentation on the accepted data formats ishere.

  You can provide either a single data object, or an iterable containingmultiple allowed data objects.

• names (eitherNone, a string, or a list of strings):

  This defines the names shown for each layer in Kepler.gl. IfNone, thelayers will be nameddata_0,data_1, and so on. Otherwise, ifdata isa single object,names should be a string, and ifdata is an iterable,thennames should be an iterable of strings.

Visualize.render()

Visualize.render(open_browser=True,read_only=False)

• read_only (boolean): IfTrue, hides side panel to disable map customization
• open_browser (boolean): IfTrue, opens the saved HTML file in the default browser

The most common reasons why a map is not displayed are:

• Missing Mapbox API Key: in order to display Mapbox-hosted maps, you need getan API key from Mapbox to pass an API key
• Data projection: Kepler.gl works only with data projected into standard WGS84 (latitude, longitude) coordinates. If you have your data in a projected coordinate system, first reproject your data into WGS84 (EPGS 4326), then try again. The CLI attempts to automatically reproject into EPSG 4326, but the Python library doesn't.

If your data seems to be "floating" above the map, this is likely because yourinput data have Z coordinates, so kepler.gl displays them in 3-dimensionalspace.