View all files | ||||
A CLI and Python API for quickly viewing geospatial data in Kepler.gl.
Uber's open-source kepler.gl is a great browser-based platform for interactively visualizing geospatial data. The keplergl Python package's included documentation is 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:
from Python:
Mapbox API key: in order to display Mapbox-hosted maps, you need to provide a Mapbox API key. Go to Mapbox.com to get an API key.
Package install:
This package has dependencies on geojson, shapely, and geopandas. 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.:
The CLI is installed under the name kepler:
You can add export MAPBOX_API_KEY to your .bashrc or .zshrc to not have to run that step each time.
You can supply filename paths to data in any vector format readable by GeoPandas/GDAL. Alternatively you can supply GeoJSON or newline-delimited GeoJSON on stdin.
Supply --help to see the CLI's help menu:
Simplest usage:
More detail over the objects in your map:
Visualize
data (either None, a single data object, or a list of data objects):
A data object may be a GeoDataFrame from the GeoPandas library, any geometry from the Shapely library, any object from the GeoJSON library, or any GeoJSON str or dict. You can also provide a CSV file as a string or a Pandas DataFrame if the DataFrame has Latitude and Longitude columns. Full documentation on the accepted data formats is here.
You can provide either a single data object, or an iterable containing multiple allowed data objects.
If data is not None, then Visualize(data) will perform all steps, including rendering the data to an HTML file and opening it in a new browser tab.
names (either None, a string, or a list of strings):
This defines the names shown for each layer in Kepler.gl. If None, the layers will be named data_0, data_1, and so on. Otherwise, if data is a single object, names should be a string, and if data is an iterable, then names should be an iterable of strings.
read_only (boolean): If True, hides side panel to disable map customization
api_key (string): Mapbox API key. Go to Mapbox.com to get an API key. If not provided, the MAPBOX_API_KEY environment variable must be set, or the style_url must point to a style.json file that does not use Mapbox map tiles.
style (string): The basemap style to use. Standard Mapbox options are:
The default is streets. Alternatively, you can supply a path to a custom style. A custom style created from Mapbox Studio should have a url that starts with mapbox://. Otherwise, a custom style using third-party map tiles should be a URL to a JSON file that conforms to the Mapbox Style Specification.
Visualize.add_data()
data (either a single data object, or a list of data objects):
A data object may be a GeoDataFrame from the GeoPandas library, any geometry from the Shapely library, any object from the GeoJSON library, or any GeoJSON string or dictionary. You can also provide a CSV file as a string or a Pandas DataFrame if the DataFrame has Latitude and Longitude columns. Full documentation on the accepted data formats is here.
You can provide either a single data object, or an iterable containing multiple allowed data objects.
names (either None, a string, or a list of strings):
This defines the names shown for each layer in Kepler.gl. If None, the layers will be named data_0, data_1, and so on. Otherwise, if data is a single object, names should be a string, and if data is an iterable, then names should be an iterable of strings.
Visualize.render()
The most common reasons why a map is not displayed are:
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.