LogoLogo
  • Welcome
  • What's new?
  • Docs
    • User guides
      • Get Started
      • Kepler.gl workflow
        • Add data to layers
          • Adding Data Layers
          • Create a Layer
          • Blend and Rearrange Layers
          • Hide, Edit and Delete Layers
        • Add Data to the Map
      • Layers
        • Point
        • S2 Layer
        • Icon
        • Line
        • Cluster
        • Polygon
        • Hexbin
        • Grid
        • H3
        • Heatmap
        • Arc
        • Trip layer
      • Layer Attributes
      • Color Palettes
      • Filters
      • Map Styles
      • Interactions
      • Map Settings
      • Time Playback
      • Save and Export
      • FAQ
    • API Reference
      • ecosystem
      • Get Started
      • Advanced usages
        • Saving and Loading Maps with Schema Manager
        • Replace UI Component with Component Dependency Injection
        • Forward Dispatch Actions
        • Reducer Plugin
        • Using Updaters
        • Custom reducer initial state
        • custom-mapbox-host
      • Components
      • Reducers
        • reducers
        • map-style
        • map-state
        • combine
        • overview
        • ui-state
        • vis-state
      • Processors
        • All processors
      • Schemas
      • Actions
        • All actions
      • Cloud providers
        • Provider
      • Custom theme
      • Localization
    • Jupyter Notebook
  • Examples
    • Node/Express
    • Demo App
    • Open modal
    • Open modal
    • UMD client
    • Customize kepler.gl Theme
    • Customize kepler.gl Reducer
  • Contributing
    • Developing Kepler.gl
    • Contributor Covenant Code of Conduct
  • Change Log
  • Upgrade Guide
Powered by GitBook
On this page
  • Ways to Add Data
  • Supported Projection Coordinate System
  • Supported File Formats
  • CSV
  • GeoJSON
  • GeoArrow
  • kepler.gl JSON
  • Load Map Using URL
  • Use Kepler.gl’s Sample Maps
  • Add multiple datasets

Was this helpful?

  1. Docs
  2. User guides
  3. Kepler.gl workflow

Add Data to the Map

PreviousHide, Edit and Delete LayersNextLayers

Last updated 1 year ago

Was this helpful?

Ways to Add Data

  • Open kepler.gl/demo. You should see the following prompt:

Add data to the map pop up

kepler.gl is a pure client side app. Data lives only in your machine/browser. No information or maps is sent back up to our server.

  • Choose one of three ways to add data to your map

Local files

Upload CSV / GeoJSON files. Because data is only stored in your browser, there is a 250mb limit on how much data Chrome allows you to upload into a browser. For datasets larger than 250mb you should directly load them from a remote URL. See below.

From URL

Directly load data or map json by pasting a remote URL. You can link it to CSV

Sample data

Supported Projection Coordinate System

Geometry coordinates should be presented with a geographic coordinate reference system, using the WGS84 datum, and with longitude and latitude units of decimal degrees.

Supported File Formats

CSV

CSV file should contain header row and multiple columns. Each row should be 1 feature. Each column should contain only 1 data type, based on which kepler.gl will use to create layers and filters.

id
point_latitude
point_longitude
value
start_time

a

31.2384

-127.30948

5

2019-08-01 12:00

b

31.2311

-127.30231

11

2019-08-01 12:05

c

31.2334

-127.30238

9

2019-08-01 11:55

1. Data type detection

Because CSV file content is uploaded as strings, kepler.gl will attempt to detect column data type by parsing a sample of data in each column. kepler.gl can detect

type
data

boolean

True, False

date

2019-01-01

geojson

WKT string: POLYGON ((-74.158 40.835, -74.148 40.830, -74.151 40.832, -74.158 40.835)), or GeoJson String {"type":"Polygon","coordinates":[[[-74.158,40.835],[-74.157,40.839],[-74.148,40.830],[-74.150,40.833],[-74.151,40.832],[-74.158,40.835]]]}

integer

1, 2, 3

real

-74.158, 40.832

string

hello, world

timestamp

2018-09-01 00:00, 1570306147, 1570306147000

Note: Make sure to clean up values such as N/A, Null, . If your column contains mixed type, kepler.gl will treat it as string to be safe.

2. Layer detection based on column names

kepler.gl will auto detect layer, if the column names follows certain naming convention. kepler.gl creates a point layer if your CSV has columns that are named <name>_lat and <name>_lng or <name>_latitude and <name>_longitude, or <name>_lat and <name>_lon.

layer
auto create layer from column names

Point

Point layer names have to be in pairs, and ends with <foo>lat, <foo>lng; <foo>latitude, <foo>longitude; <foo>lat, <foo>lon

Arc

If two points layers are detected, one arc layer will be created

Icon

A column named icon is present

H3

A column named h3_id or hexagon_id is present

Polygon

3. Embed Geometries in CSV

Geometries (Polygons, Points, LindStrings etc) can be embedded into CSV as a GeoJSON or WKT formatted string.

GeoJSON String

Example data.csv with GeoJSON

id,geometry
1,"{""type"":""Polygon"",""coordinates"":[[[-74.158491,40.835947],[-74.157914,40.83902]]]}"

WKTString

Example data.csv with WKT

id,geometry
1,"POLYGON((0 0,10 0,10 10,0 10,0 0),(5 5,7 5,7 7,5 7, 5 5))"

GeoJSON

1. Feature types

    • A single GeoJSON Feature:

      {
        "type": "Feature",
        "geometry": {
          "type": "Polygon",
          "coordinates": [
            [
              [-10.0, -10.0],
              [10.0, -10.0],
              [10.0, 10.0],
              [-10.0, -10.0]
            ]
          ]
        },
        "properties": {
          "name": "foo"
        }
      }
    • GeoJSON Feature Collection.

    {
      "type": "FeatureCollection",
      "features": [{
          "type": "Feature",
          "geometry": {
              "type": "Point",
              "coordinates": [102.0, 0.5]
          },
          "properties": {
              "prop0": "value0"
          }
      }, {
          "type": "Feature",
          "geometry": {
              "type": "LineString",
              "coordinates": [
                  [102.0, 0.0],
                  [103.0, 1.0],
                  [104.0, 0.0],
                  [105.0, 1.0]
              ]
          },
          "properties": {
            "prop0": "value0"
          }
      }]
    }

    kepler.gl will render all features in one Polygon layer even though they have different geometry types. Acceptable geometry types are

    Feature properties will be parsed as columns. You can apply color, filters based on them.

2. Auto styling

kepler.gl will read styles from GeoJSON files. If you are a GeoJSON expert, you can add style declarations to feature properties. kepler.gl will use the declarations to automatically style your feature. The acceptable style properties are:

"properties": {
  "lineColor": [130, 154, 227],
  "lineWidth": 0.5,
  "fillColor": [255, 0, 0],
  "radius": 1 // Point
}
  • See an example below:

{
  "type": "FeatureCollection",
  "features": [{
      "type": "Feature",
      "geometry": {
        "type": "LineString",
        "coordinates": [
          [-105.1547889, 39.9862516],
          [-105.1547167, 39.9862691]
        ]
      },
      "properties": {
        "id": "a1398a11-d1ce-421c-bf66-a456ff525de9",
        "lineColor": [130, 154, 227],
        "lineWidth": 0.1
      }
  }]
}

GeoArrow

kepler.gl JSON

Load Map Using URL

You load data or map through custom URL. It currently supports URLs with file extension of csv, json and kepler.gl.json

In addition, this also by-passes 250mb file upload size limit which allows you to upload larger file to Kepler.

Use Kepler.gl’s Sample Maps

The sample maps are a great option for new users to explore Kepler.gl and get a feel for how it works.

  1. At the initial load prompt select “Try sample data” in the top right corner.

  1. Choose from the options to load the sample map and explore the configurations applied.

Add multiple datasets

To add additional datasets to your map:

  1. Click Add More Data in the top right corner.

  1. Choose one of the options above: upload a JSON/CSV file, or use Kepler.gl’s sample data.

  2. Repeat as needed. There is no limit on the number of datasets you can add. However, adding too many might cause its performance to suffer.

Load one of kepler.gl’s sample datasets. The sample map data and config are directly loaded from repo

kepler.gl only supports EPSG:3857 -- WGS84.

A column content contains geojson data types. Acceptable formats include e.g. POLYGON ((-74.158 40.835, -74.148 40.830, -74.151 40.832, -74.158 40.835)) and . e.g. {"type":"LineString","coordinates":[[100.0, 0.0],[101.0, 1.0]]}

Use the geometry of a Feature, which includes type and coordinates. It should be a JSON formatted string, with the " corrected escaped. More info on

representation of geometry values is designed for exchanging geometry data in ASCII form.

kepler.gl accepts GeoJSON formatted JSON that contains a single object or a object. kepler.gl creates one Polygon layer per GeoJSON file.

.

file, a binary data format which can be visualized with the .

JSON file exported from kepler.gl. See "".

Load Map Using URL
Try sample data pop up
Choose sample data pop up
Add more data

Web Mercator
String escape in csv
The Well-Known Text (WKT)
Feature
FeatureCollection
Point
MultiPoint
LineString
MultiLineString
Polygon
MultiPolygon
GeoArrow
PolygonLayer
Export Map as JSON
Back to table of contents
CSV
GeoJSON
GeoArrow
kepler.gl Json
kepler.gl-data github
Well-Known Text
GeoJSON Geometry