{"id":18174820,"url":"https://github.com/kylebarron/keplergl_cli","last_synced_at":"2025-09-06T16:33:18.470Z","repository":{"id":41036759,"uuid":"226220115","full_name":"kylebarron/keplergl_cli","owner":"kylebarron","description":"One-line geospatial data visualization using Kepler.gl","archived":false,"fork":false,"pushed_at":"2022-12-26T21:00:03.000Z","size":6575,"stargazers_count":36,"open_issues_count":3,"forks_count":6,"subscribers_count":3,"default_branch":"master","last_synced_at":"2024-12-23T07:28:02.271Z","etag":null,"topics":["cli","data-visualization","geospatial","kepler-gl","mapbox","python"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/kylebarron.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.rst","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2019-12-06T01:23:28.000Z","updated_at":"2024-11-30T15:27:37.000Z","dependencies_parsed_at":"2023-01-31T01:45:56.360Z","dependency_job_id":null,"html_url":"https://github.com/kylebarron/keplergl_cli","commit_stats":null,"previous_names":["kylebarron/keplergl_quickvis"],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kylebarron%2Fkeplergl_cli","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kylebarron%2Fkeplergl_cli/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kylebarron%2Fkeplergl_cli/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kylebarron%2Fkeplergl_cli/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kylebarron","download_url":"https://codeload.github.com/kylebarron/keplergl_cli/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":232133632,"owners_count":18477294,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cli","data-visualization","geospatial","kepler-gl","mapbox","python"],"created_at":"2024-11-02T16:07:52.513Z","updated_at":"2025-01-01T22:42:37.617Z","avatar_url":"https://github.com/kylebarron.png","language":"Python","readme":"# keplergl_cli\n\nA CLI and Python API for quickly viewing geospatial data in Kepler.gl.\n\n## Overview\n\nUber's open-source [kepler.gl](https://kepler.gl/) is a great browser-based\nplatform for interactively visualizing geospatial data. The `keplergl` Python package's [included\ndocumentation](https://github.com/keplergl/kepler.gl/blob/master/docs/keplergl-jupyter/user-guide.md)\nis almost entirely directed at use within Jupyter, and it took a little bit of\nwork to figure out how to use it from a non-Jupyter Python environment.\n\nThis package is a simple wrapper to quickly get your data into kepler.gl. From\nthe command line, it's as simple as:\n\n```\nexport MAPBOX_API_KEY=...\nkeplergl data1.geojson data2.shp data3.gdb\ncat data.geojson | keplergl\n```\n\nfrom Python:\n\n```py\nfrom keplergl_cli import Visualize\nVisualize(data)\n```\n\n![Example gif](https://raw.githubusercontent.com/kylebarron/keplergl_cli/master/assets/example.gif)\n\n## Features\n\n-   One-line data visualization\n-   Automatically converts Shapely objects to GeoJSON\n-   Supports piped GeoJSON input\n-   No configuration needed\n\n## Install\n\n**Mapbox API key**: in order to display Mapbox-hosted maps, you need to provide\na Mapbox API key. Go to [Mapbox.com](https://account.mapbox.com/access-tokens)\nto get an API key.\n\n**Package install**:\n\n```\npip install keplergl_cli\n```\n\nThis package has dependencies on `geojson`, `shapely`, and `geopandas`. If you\nget errors when installing this package through pip, it may be easier to first\ninstall dependencies through Conda, then install this package. I.e.:\n\n```\nconda install geojson shapely geopandas -c conda-forge\npip install keplergl_cli\n```\n\n## Usage\n\n### CLI\n\nThe CLI is installed under the name `kepler`:\n\n```\nexport MAPBOX_API_KEY=...\nkepler --style=outdoors data.geojson\nkepler --style=dark data1.geojson shapefile.shp geodatabase.gdb -l layer1 -l layer2\ncat data.geojson | kepler\n```\n\nYou can add `export MAPBOX_API_KEY` to your `.bashrc` or `.zshrc` to not have to\nrun that step each time.\n\nYou can supply filename paths to data in any [vector format readable by\nGeoPandas/GDAL](https://gdal.org/drivers/vector/index.html). Alternatively you\ncan supply GeoJSON or newline-delimited GeoJSON on stdin.\n\nSupply `--help` to see the CLI's help menu:\n\n```\n\u003e kepler --help\n\nUsage: kepler [OPTIONS] FILES...\n\n  Interactively view geospatial data using kepler.gl\n\nOptions:\n  -l, --layer TEXT  Layer names. If not provided, will display all layers\n  --api_key TEXT    Mapbox API Key. Must be provided on the command line or\n                    exist in the MAPBOX_API_KEY environment variable.\n  --style TEXT      Mapbox style. Accepted values are: streets, outdoors,\n                    light, dark, satellite, satellite-streets, or a custom\n                    style URL.  [default: streets]\n  --help            Show this message and exit.\n```\n\n### Python API\n\nSimplest usage:\n\n```py\nimport geopandas as gpd\nfrom keplergl_cli import Visualize\n\n# Create your geospatial objects\ngdf = gpd.GeoDataFrame(...)\n\n# Visualize one or multiple objects at a time\nVisualize(gdf, api_key=MAPBOX_API_KEY)\nVisualize([gdf, shapely_object, geojson_string], api_key=MAPBOX_API_KEY)\n```\n\nMore detail over the objects in your map:\n\n```py\nfrom keplergl_cli import Visualize\nvis = Visualize(api_key=MAPBOX_API_KEY)\nvis.add_data(data=data, names='name of layer')\nvis.add_data(data=data2, names='name of layer')\nhtml_path = vis.render(open_browser=True, read_only=False)\n```\n\n**Visualize**\n\n```py\nVisualize(data=None, names=None, read_only=False, api_key=None, style=None)\n```\n\n-   `data` (either `None`, a single data object, or a list of data objects):\n\n    A data object may be a GeoDataFrame from the\n    [GeoPandas](http://geopandas.org/) library, any geometry from the\n    [Shapely](https://shapely.readthedocs.io/en/stable/manual.html) library, any\n    object from the [GeoJSON](https://github.com/jazzband/geojson) library, or\n    any GeoJSON `str` or `dict`. You can also provide a CSV file as a\n    string or a Pandas DataFrame if the DataFrame has `Latitude` and `Longitude`\n    columns. Full documentation on the accepted data formats is\n    [here](https://github.com/keplergl/kepler.gl/blob/master/docs/keplergl-jupyter/user-guide.md#3-data-format).\n\n    You can provide either a single data object, or an iterable containing\n    multiple allowed data objects.\n\n    If data is not `None`, then Visualize(data) will perform all steps, including\n    rendering the data to an HTML file and opening it in a new browser tab.\n\n-   `names` (either `None`, a string, or a list of strings):\n\n    This defines the names shown for each layer in Kepler.gl. If `None`, the\n    layers will be named `data_0`, `data_1`, and so on. Otherwise, if `data` is\n    a single object, `names` should be a string, and if `data` is an iterable,\n    then `names` should be an iterable of strings.\n\n-   `read_only` (`boolean`): If `True`, hides side panel to disable map customization\n-   `api_key` (`string`): Mapbox API key. Go to [Mapbox.com](https://account.mapbox.com/access-tokens)\n    to get an API key. If not provided, the `MAPBOX_API_KEY` environment\n    variable must be set, or the `style_url` must point to a `style.json` file\n    that does not use Mapbox map tiles.\n-   `style` (`string`): The basemap style to use. Standard Mapbox options are:\n\n    -   `streets`\n    -   `outdoors`\n    -   `light`\n    -   `dark`\n    -   `satellite`\n    -   `satellite-streets`\n\n    The default is `streets`. Alternatively, you can supply a path to a custom\n    style. A custom style created from Mapbox Studio should have a url that\n    starts with `mapbox://`. Otherwise, a custom style using third-party map\n    tiles should be a URL to a JSON file that conforms to the [Mapbox Style\n    Specification](https://docs.mapbox.com/mapbox-gl-js/style-spec/).\n\n**Visualize.add_data()**\n\n```py\nVisualize.add_data(data, names=None):\n```\n\n-   `data` (either a single data object, or a list of data objects):\n\n    A data object may be a GeoDataFrame from the\n    [GeoPandas](http://geopandas.org/) library, any geometry from the\n    [Shapely](https://shapely.readthedocs.io/en/stable/manual.html) library, any\n    object from the [GeoJSON](https://github.com/jazzband/geojson) library, or\n    any GeoJSON string or dictionary. You can also provide a CSV file as a\n    string or a Pandas DataFrame if the DataFrame has `Latitude` and `Longitude`\n    columns. Full documentation on the accepted data formats is\n    [here](https://github.com/keplergl/kepler.gl/blob/master/docs/keplergl-jupyter/user-guide.md#3-data-format).\n\n    You can provide either a single data object, or an iterable containing\n    multiple allowed data objects.\n\n-   `names` (either `None`, a string, or a list of strings):\n\n    This defines the names shown for each layer in Kepler.gl. If `None`, the\n    layers will be named `data_0`, `data_1`, and so on. Otherwise, if `data` is\n    a single object, `names` should be a string, and if `data` is an iterable,\n    then `names` should be an iterable of strings.\n\n**Visualize.render()**\n\n```py\nVisualize.render(open_browser=True, read_only=False)\n```\n\n-   `read_only` (`boolean`): If `True`, hides side panel to disable map customization\n-   `open_browser` (`boolean`): If `True`, opens the saved HTML file in the default browser\n\n## Troubleshooting\n\nThe most common reasons why a map is not displayed are:\n\n-   Missing Mapbox API Key: in order to display Mapbox-hosted maps, you need get [an API key from Mapbox](https://account.mapbox.com/access-tokens) to pass an API key\n-   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.\n\nIf your data seems to be \"floating\" above the map, this is likely because your\ninput data have Z coordinates, so kepler.gl displays them in 3-dimensional\nspace.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkylebarron%2Fkeplergl_cli","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkylebarron%2Fkeplergl_cli","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkylebarron%2Fkeplergl_cli/lists"}