Package: keplergl-cli
keplergl_cliA CLI and Python API for quickly viewing geospatial data in Kepler.gl.OverviewUber's open-sourcekepler.glis a great browser-based
platform for interactively visualizing geospatial data. ThekeplerglPython package'sincluded
documentationis almost entirely directed at use within Jupyter, and it took a little bit of
work 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. From
the command line, it's as simple as:export MAPBOX_API_KEY=...
keplergl data1.geojson data2.shp data3.gdb
cat data.geojson | keplerglfrom Python:fromkeplergl_cliimportVisualizeVisualize(data)FeaturesOne-line data visualizationAutomatically converts Shapely objects to GeoJSONSupports piped GeoJSON inputNo configuration neededInstallMapbox API key: in order to display Mapbox-hosted maps, you need to provide
a Mapbox API key. Go toMapbox.comto get an API key.Package install:pip install keplergl_cliThis package has dependencies ongeojson,shapely, andgeopandas. If you
get errors when installing this package through pip, it may be easier to first
install dependencies through Conda, then install this package. I.e.:conda install geojson shapely geopandas -c conda-forge
pip install keplergl_cliUsageCLIThe CLI is installed under the namekepler:export MAPBOX_API_KEY=...
kepler --style=outdoors data.geojson
kepler --style=dark data1.geojson shapefile.shp geodatabase.gdb -l layer1 -l layer2
cat data.geojson | keplerYou can addexport MAPBOX_API_KEYto your.bashrcor.zshrcto not have to
run that step each time.You can supply filename paths to data in anyvector format readable by
GeoPandas/GDAL. Alternatively you
can supply GeoJSON or newline-delimited GeoJSON on stdin.Supply--helpto see the CLI's help menu:> kepler --help

Usage: kepler [OPTIONS] FILES...

  Interactively view geospatial data using kepler.gl

Options:
  -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.Python APISimplest 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)VisualizeVisualize(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 theGeoPandaslibrary, any geometry from theShapelylibrary, any
object from theGeoJSONlibrary, or
any GeoJSONstrordict. You can also provide a CSV file as a
string or a Pandas DataFrame if the DataFrame hasLatitudeandLongitudecolumns. Full documentation on the accepted data formats ishere.You can provide either a single data object, or an iterable containing
multiple allowed data objects.If data is notNone, then Visualize(data) will perform all steps, including
rendering 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, the
layers will be nameddata_0,data_1, and so on. Otherwise, ifdatais
a single object,namesshould be a string, and ifdatais an iterable,
thennamesshould be an iterable of strings.read_only(boolean): IfTrue, hides side panel to disable map customizationapi_key(string): Mapbox API key. Go toMapbox.comto get an API key. If not provided, theMAPBOX_API_KEYenvironment
variable must be set, or thestyle_urlmust point to astyle.jsonfile
that does not use Mapbox map tiles.style(string): The basemap style to use. Standard Mapbox options are:streetsoutdoorslightdarksatellitesatellite-streetsThe default isstreets. Alternatively, you can supply a path to a custom
style. A custom style created from Mapbox Studio should have a url that
starts withmapbox://. Otherwise, a custom style using third-party map
tiles should be a URL to a JSON file that conforms to theMapbox Style
Specification.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 theGeoPandaslibrary, any geometry from theShapelylibrary, any
object from theGeoJSONlibrary, or
any GeoJSON string or dictionary. You can also provide a CSV file as a
string or a Pandas DataFrame if the DataFrame hasLatitudeandLongitudecolumns. Full documentation on the accepted data formats ishere.You can provide either a single data object, or an iterable containing
multiple allowed data objects.names(eitherNone, a string, or a list of strings):This defines the names shown for each layer in Kepler.gl. IfNone, the
layers will be nameddata_0,data_1, and so on. Otherwise, ifdatais
a single object,namesshould be a string, and ifdatais an iterable,
thennamesshould 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 customizationopen_browser(boolean): IfTrue, opens the saved HTML file in the default browserTroubleshootingThe 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 Mapboxto pass an API keyData 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 your
input data have Z coordinates, so kepler.gl displays them in 3-dimensional
space.Changelog0.3.3 (2022-06-27)Revert usage of__geo_interface__0.3.2 (2022-06-27)Use__geo_interface__when possibleRespectopen_browser=FalseFix centering map0.3.1 (2020-02-26)Fix for stdin0.3.0 (2020-02-26)Support GeoJSON on stdinRenamekeplergl_quickvistokeplergl_cliRename CLI entry point tokeplerCLI option for which layers from file to display0.2.0 (2019-12-09)Automatically attempt to reproject to EPSG 43260.1.0 (2019-12-05)First release on PyPI.