kepler.gl
Tools
TypeScript
<p>
</a>
</p>
<p>
<a rel="nofollow noopener" target="_blank" href="https://app.netlify.com/sites/keplergl/deploys" alt="Netlify Status"></p>
<p>
</a>
</p>
<h1 align="center" dir="auto">
<a rel="nofollow noopener" target="_blank" id="user-content---keplergl--website--demo-app--docs" class="anchor" aria-hidden="true" href="#--keplergl--website--demo-app--docs"></a><br /> kepler.gl | <a rel="nofollow noopener" target="_blank" href="http://kepler.gl">Website</a> | <a rel="nofollow noopener" target="_blank" href="http://kepler.gl/#/demo">Demo App</a> | <a rel="nofollow noopener" target="_blank" href="https://docs.kepler.gl/">Docs</a><br />
</h1>
<h3 dir="auto">
</h3>
<p>
<a rel="nofollow noopener" target="_blank" href="http://kepler.gl"></a><br /> <a rel="nofollow noopener" target="_blank" href="http://kepler.gl/#/demo"></a><br /> <a rel="nofollow noopener" target="_blank" href="http://www.kepler.gl/">Kepler.gl</a> is a data-agnostic, high-performance web-based application for visual exploration of large-scale geolocation data sets. Built on top of <a rel="nofollow noopener" target="_blank" href="https://www.mapbox.com">Mapbox GL</a> and <a rel="nofollow noopener" target="_blank" href="http://uber.github.io/deck.gl/#/">deck.gl</a>, kepler.gl can render millions of points representing thousands of trips and perform spatial aggregations on the fly.<br /> Kepler.gl is also a React component that uses <a rel="nofollow noopener" target="_blank" href="https://redux.js.org/">Redux</a> to manage its state and data flow. It can be embedded into other React-Redux applications and is highly customizable. For information on how to embed kepler.gl in your app take a look at this step-by-step <a rel="nofollow noopener" target="_blank" href="http://vis.academy/#/kepler.gl/">tutorial</a> on vis.academy.
</p>
<h2 dir="auto">
<a rel="nofollow noopener" target="_blank" id="user-content-links" class="anchor" aria-hidden="true" href="#links"></a>Links
</h2>
<ul dir="auto">
<li>
<a rel="nofollow noopener" target="_blank" href="http://www.kepler.gl/">Website</a>
</li>
<li>
<a rel="nofollow noopener" target="_blank" href="http://kepler.gl/#/demo">Demo</a>
</li>
<li>
Examples
</li>
<li>
Get Started
</li>
<li>
App User Guide
</li>
<li>
Jupyter Widget User Guide
</li>
<li>
<a rel="nofollow noopener" target="_blank" href="http://vis.academy/#/kepler.gl/">Tutorial</a>
</li>
<li>
<a rel="nofollow noopener" target="_blank" href="https://stackoverflow.com/questions/tagged/kepler.gl">Stack Overflow</a>
</li>
<li>
Contribution Guidelines
</li>
<li>
Api Reference
</li>
<li>
Roadmap
</li>
</ul>
<h2 dir="auto">
<a rel="nofollow noopener" target="_blank" id="user-content-env" class="anchor" aria-hidden="true" href="#env"></a>Env
</h2>
<p>
Use Node 10.15.0 or above, older node versions have not been supported/ tested.<br /> For best results, use nvm <code>nvm install</code>.
</p>
<h2 dir="auto">
<a rel="nofollow noopener" target="_blank" id="user-content-install-keplergl" class="anchor" aria-hidden="true" href="#install-keplergl"></a>Install kepler.gl
</h2>
<p>
Install node (<code>> 10.15.0</code>), yarn, and project dependencies
</p>
<pre>npm install --save kepler.gl
// or yarn add kepler.gl
<p>
kepler.gl is built upon <a rel="nofollow noopener" target="_blank" href="https://www.mapbox.com">mapbox</a>. You will need a <a rel="nofollow noopener" target="_blank" href="https://www.mapbox.com/help/define-access-token/">Mapbox Access Token</a> to use it.<br /> If you don’t use a module bundler, it’s also fine. Kepler.gl npm package includes precompiled production UMD builds in the <a rel="nofollow noopener" target="_blank" href="https://unpkg.com/kepler.gl/umd">umd folder</a>.<br /> You can add the script tag to your html file as it follows:
</p>
<pre><script src="https://unpkg.com/kepler.gl/umd/keplergl.min.js" /></pre>
<p>
or if you would like, you can load a specific version
</p>
<pre><script src="https://unpkg.com/kepler.gl@0.2.2/umd/keplergl.min.js" /></pre>
<h2 dir="auto">
<a rel="nofollow noopener" target="_blank" id="user-content-develop-keplergl" class="anchor" aria-hidden="true" href="#develop-keplergl"></a>Develop kepler.gl
</h2>
<p>
Take a look at the development guide to develop kepler.gl locally.
</p>
<h2 dir="auto">
<a rel="nofollow noopener" target="_blank" id="user-content-basic-usage" class="anchor" aria-hidden="true" href="#basic-usage"></a>Basic Usage
</h2>
<p>
Here are the basic steps to import kepler.gl into your app. You also take a look at the examples folder. Each example in the folder can be installed and run locally.
</p>
<h3 dir="auto">
<a rel="nofollow noopener" target="_blank" id="user-content-1-mount-reducer" class="anchor" aria-hidden="true" href="#1-mount-reducer"></a>1. Mount reducer
</h3>
<p>
Kepler.gl uses Redux to manage its internal state, along with react-palm middleware to handle side effects.<br /> You need to add <code>taskMiddleware</code> of <code>react-palm</code> to your store too. We are actively working on a solution where<br /> <code>react-palm</code> will not be required, however it is still a very lightweight side effects management tool that is easier to test than react-thunk.
</p>
<pre>import {createStore, combineReducers, applyMiddleware, compose} from 'redux';
import keplerGlReducer from ‘kepler.gl/reducers’; import {enhanceReduxMiddleware} from ‘kepler.gl/middleware’;
const initialState = {}; const reducers = combineReducers({ // <– mount kepler.gl reducer in your app keplerGl: keplerGlReducer,
// Your other reducers here app: appReducer });
// using createStore export default createStore( reducer, initialState, applyMiddleware( enhanceReduxMiddleware([ /* Add other middlewares here */ ]) ) );
<p>
Or if use enhancer:
</p>
<pre>// using enhancers
const initialState = {}; const middlewares = enhanceReduxMiddleware([ // Add other middlewares here ]); const enhancers = [applyMiddleware(…middlewares)];
export default createStore(reducer, initialState, compose(…enhancers));
<p>
If you mount kepler.gl reducer in another address instead of <code>keplerGl</code>, or the kepler.gl reducer is not<br /> mounted at root of your state, you will need to specify the path to it when you mount the component<br /> with the <code>getState</code> prop.<br /> Read more about Reducers.
</p>
<h3 dir="auto">
<a rel="nofollow noopener" target="_blank" id="user-content-2-mount-component" class="anchor" aria-hidden="true" href="#2-mount-component"></a>2. Mount Component
</h3>
<pre>import KeplerGl from 'kepler.gl';
const Map = props => ( <KeplerGl id=“foo” width={width} mapboxApiAccessToken={token} height={height} /> );
<h4 dir="auto">
<a rel="nofollow noopener" target="_blank" id="user-content-props" class="anchor" aria-hidden="true" href="#props"></a>Props
</h4>
<h5 dir="auto">
<a rel="nofollow noopener" target="_blank" id="user-content-id-string-required" class="anchor" aria-hidden="true" href="#id-string-required"></a><code>id</code> (String, required)
</h5>
<ul dir="auto">
<li>
Default: <code>map</code>
</li>
</ul>
<p>
The id of this KeplerGl instance. <code>id</code> is required if you have multiple<br /> KeplerGl instances in your app. It defines the prop name of the KeplerGl state that is<br /> stored in the KeplerGl reducer. For example, the state of the KeplerGl component with id <code>foo</code> is<br /> stored in <code>state.keplerGl.foo</code>.<br /> In case you create multiple kepler.gl instances using the same id, the kepler.gl state defined by the entry will be<br /> overridden by the latest instance and reset to a blank state.
</p>
<h5 dir="auto">
<a rel="nofollow noopener" target="_blank" id="user-content-mapboxapiaccesstoken-string-required" class="anchor" aria-hidden="true" href="#mapboxapiaccesstoken-string-required"></a><code>mapboxApiAccessToken</code> (String, required*)
</h5>
<ul dir="auto">
<li>
Default: <code>undefined</code>
</li>
</ul>
<p>
By default, kepler.gl uses mapbox-gl.js to render its base maps. You can create a free account at <a rel="nofollow noopener" target="_blank" href="https://www.mapbox.com">mapbox</a> and create a token at <a rel="nofollow noopener" target="_blank" href="https://www.mapbox.com/help/define-access-token/">www.mapbox.com/account/access-tokens</a>.<br /> If you replaced kepler.gl default map styles with your own, and they are not Mapbox styles. <code>mapboxApiAccessToken</code> will not be reuiqred.<br /> Read more about Custom Map Styles.
</p>
<h5 dir="auto">
<a rel="nofollow noopener" target="_blank" id="user-content-getstate-function-optional" class="anchor" aria-hidden="true" href="#getstate-function-optional"></a><code>getState</code> (Function, optional)
</h5>
<ul dir="auto">
<li>
Default: <code>state => state.keplerGl</code>
</li>
</ul>
<p>
The path to the root keplerGl state in your reducer.
</p>
<h5 dir="auto">
<a rel="nofollow noopener" target="_blank" id="user-content-width-number-optional" class="anchor" aria-hidden="true" href="#width-number-optional"></a><code>width</code> (Number, optional)
</h5>
<ul dir="auto">
<li>
Default: <code>800</code>
</li>
</ul>
<p>
Width of the KeplerGl UI.
</p>
<h5 dir="auto">
<a rel="nofollow noopener" target="_blank" id="user-content-height-number-optional" class="anchor" aria-hidden="true" href="#height-number-optional"></a><code>height</code> (Number, optional)
</h5>
<ul dir="auto">
<li>
Default: <code>800</code>
</li>
</ul>
<h5 dir="auto">
<a rel="nofollow noopener" target="_blank" id="user-content-appname-string-optional" class="anchor" aria-hidden="true" href="#appname-string-optional"></a><code>appName</code> (String, optional)
</h5>
<ul dir="auto">
<li>
Default: <code>Kepler.Gl</code>
</li>
</ul>
<p>
App name displayed in side panel header
</p>
<h5 dir="auto">
<a rel="nofollow noopener" target="_blank" id="user-content-version-string-optional" class="anchor" aria-hidden="true" href="#version-string-optional"></a><code>version</code> (String, optional)
</h5>
<ul dir="auto">
<li>
Default: <code>v1.0</code>
</li>
</ul>
<p>
version displayed in side panel header
</p>
<h5 dir="auto">
<a rel="nofollow noopener" target="_blank" id="user-content-onsavemap-function-optional" class="anchor" aria-hidden="true" href="#onsavemap-function-optional"></a><code>onSaveMap</code> (Function, optional)
</h5>
<ul dir="auto">
<li>
Default: <code>undefined</code>
</li>
</ul>
<p>
Action called when click Save Map Url in side panel header.
</p>
<h5 dir="auto">
<a rel="nofollow noopener" target="_blank" id="user-content-onviewstatechange-function-optional" class="anchor" aria-hidden="true" href="#onviewstatechange-function-optional"></a><code>onViewStateChange</code> (Function, optional)
</h5>
<ul dir="auto">
<li>
Default: <code>undefined</code>
</li>
<li>
Parameter: <code>viewState</code> – An updated view state object containing parameters such as longitude, latitude, zoom etc
</li>
</ul>
<p>
Action triggered when map viewport is updated.
</p>
<h5 dir="auto">
<a rel="nofollow noopener" target="_blank" id="user-content-getmapboxrefmapbox-index-function-optional" class="anchor" aria-hidden="true" href="#getmapboxrefmapbox-index-function-optional"></a><code>getMapboxRef(mapbox, index)</code> (Function, optional)
</h5>
<ul dir="auto">
<li>
Default: <code>undefined</code>
</li>
</ul>
<p>
Function called when <code>KeplerGL</code> adds or removes a <code>MapContainer</code> component having an inner Mapbox map.<br /> The <code>mapbox</code> argument is an <a rel="nofollow noopener" target="_blank" href="https://uber.github.io/react-map-gl/#/Documentation/api-reference/interactive-map"><code>InteractiveMap</code></a> when added or <code>null</code> when removed.<br /> The <code>index</code> argument is 0 for a single map or 1 for an additional map (since <code>KeplerGL</code> supports an optional split map view).
</p>
<h5 dir="auto">
<a rel="nofollow noopener" target="_blank" id="user-content-actions-object-optional" class="anchor" aria-hidden="true" href="#actions-object-optional"></a><code>actions</code> (Object, optional)
</h5>
<ul dir="auto">
<li>
Default: <code>{}</code>
</li>
</ul>
<p>
Actions creators to replace default kepler.gl action creator. Only use custom action when you want to modify action payload.
</p>
<h5 dir="auto">
<a rel="nofollow noopener" target="_blank" id="user-content-mint-boolean-optional" class="anchor" aria-hidden="true" href="#mint-boolean-optional"></a><code>mint</code> (Boolean, optional)
</h5>
<ul dir="auto">
<li>
Default: <code>true</code>
</li>
</ul>
<p>
Whether to load a fresh empty state when component is mounted. when parse <code>mint: true</code> kepler.gl component will always load a fresh state when re-mount the same component, state inside this component will be destroyed once its unmounted.<br /> By Parsing <code>mint: false</code> kepler.gl will keep the component state in the store even when it is unmounted, and use it as initial state when re-mounted again. This is useful when mounting kepler.gl in a modal, and keep the same map when re-open.<br /> Read more about Components.
</p>
<h5 dir="auto">
<a rel="nofollow noopener" target="_blank" id="user-content-theme-object--string-optional" class="anchor" aria-hidden="true" href="#theme-object--string-optional"></a><code>theme</code> (Object | String, optional)
</h5>
<ul dir="auto">
<li>
default: <code>null</code>
</li>
</ul>
<p>
One of <code>"dark"</code>, <code>"light"</code> or <code>"base"</code><br /> You can pass theme name or object used to customize Kepler.gl style. Kepler.gl provide an <code>'light'</code> theme besides the default ‘dark’ theme. When pass in a theme object Kepler.gl will use the value passed as input to override values from theme.<br /> Read more about Custom Theme
</p>
<h4 dir="auto">
<a rel="nofollow noopener" target="_blank" id="user-content-mapboxapiurl-string-optional" class="anchor" aria-hidden="true" href="#mapboxapiurl-string-optional"></a><code>mapboxApiUrl</code> (String, optional)
</h4>
<ul dir="auto">
<li>
Default: <code>https://api.mapbox.com</code>
</li>
</ul>
<p>
If you are using your own mapbox tile server, you can pass in your own tile server api url.
</p>
<h4 dir="auto">
<a rel="nofollow noopener" target="_blank" id="user-content-mapstylesreplacedefault-boolean-optional" class="anchor" aria-hidden="true" href="#mapstylesreplacedefault-boolean-optional"></a><code>mapStylesReplaceDefault</code> (Boolean, optional)
</h4>
<ul dir="auto">
<li>
Default: <code>false</code>
</li>
</ul>
<p>
kepler.gl provide 4 map styles to choose from. Pass <code>true</code> if you want to supply your own <code>mapStyles</code>. See Below.
</p>
<h4 dir="auto">
<a rel="nofollow noopener" target="_blank" id="user-content-mapstyles-array-optional" class="anchor" aria-hidden="true" href="#mapstyles-array-optional"></a><code>mapStyles</code> (Array, optional)
</h4>
<ul dir="auto">
<li>
Default: <code>[]</code>
</li>
</ul>
<p>
You can supply additional map styles to be displayed in map style selection panel. By default, additional map styles will be added to default map styles. If pass <code>mapStylesReplaceDefault: true</code>, they will replace the default ones. kepler.gl will attempt to group layers of your style based on its <code>id</code> naming convention and use it to allow toggle visibility of base map layers. Supply your own <code>layerGroups</code> to override default for more accurate layer grouping.<br /> Each <code>mapStyles</code> should has the following properties:
</p>
<ul dir="auto">
<li>
<code>id</code> (String, required) unique string that should <strong>not</strong> be one of these reserved <code>dark</code> <code>light</code> <code>muted</code>. <code>muted_night</code>
</li>
<li>
<code>label</code> (String, required) name to be displayed in map style selection panel
</li>
<li>
<code>url</code> (String, required) mapbox style url or a url pointing to the map style json object written in <a rel="nofollow noopener" target="_blank" href="https://docs.mapbox.com/mapbox-gl-js/style-spec/">Mapbox GL Style Spec</a>.
</li>
<li>
<code>icon</code> (String, optional) image icon of the style, it can be a url, or an <a rel="nofollow noopener" target="_blank" href="https://flaviocopes.com/data-urls/#how-does-a-data-url-look">image data url</a>
</li>
<li>
<code>layerGroups</code> (Array, optional)
</li>
</ul>
<pre>const mapStyles = [
{
id: ‘my_dark_map’,
label: ‘Dark Streets 9’,
url: ‘mapbox://styles/mapbox/dark-v9’,
icon: ${apiHost}/styles/v1/mapbox/dark-v9/static/-122.3391,37.7922,9.19,0,0/400x300?access_token=${accessToken}&logo=false&attribution=false,
layerGroups: [
{
slug: ’label’,
filter: ({id}) => id.match(/(?=(label|place-|poi-))/),
defaultVisibility: true
},
{
// adding this will keep the 3d building option
slug: ‘3d building’,
filter: () => false,
defaultVisibility: false
}
]
}
];
<p>
Read more about Custom Map Styles.
</p>
<h4 dir="auto">
<a rel="nofollow noopener" target="_blank" id="user-content-initialuistate-object-optional" class="anchor" aria-hidden="true" href="#initialuistate-object-optional"></a><code>initialUiState</code> (object, optional)
</h4>
<ul dir="auto">
<li>
Default: <code>undefined</code>
</li>
</ul>
<p>
Intial UI State applied to uiState reducer, value will be shallow merged with default <a rel="nofollow noopener" target="_blank" href="https://docs.kepler.gl/docs/api-reference/reducers/ui-state#initial_ui_state"><code>INITIAL_UI_STATE</code></a>
</p>
<h4 dir="auto">
<a rel="nofollow noopener" target="_blank" id="user-content-localemessages-object-optional" class="anchor" aria-hidden="true" href="#localemessages-object-optional"></a><code>localeMessages</code> (object, optional)
</h4>
<ul dir="auto">
<li>
Default: <code>undefined</code> Modify default translation or add new translation
</li>
</ul>
<p>
Read more about Localization.
</p>
<h3 dir="auto">
<a rel="nofollow noopener" target="_blank" id="user-content-3-dispatch-custom-actions-to-keplergl-reducer" class="anchor" aria-hidden="true" href="#3-dispatch-custom-actions-to-keplergl-reducer"></a>3. Dispatch custom actions to <code>keplerGl</code> reducer.
</h3>
<p>
One advantage of using the reducer over React component state to handle keplerGl state is the flexibility<br /> to customize its behavior. If you only have one <code>KeplerGl</code> instance in your app or never intend to dispatch actions to KeplerGl from outside the component itself,<br /> you don’t need to worry about forwarding dispatch and can move on to the next section. But life is full of customizations, and we want to make yours as enjoyable as possible.<br /> There are multiple ways to dispatch actions to a specific <code>KeplerGl</code> instance.
</p>
<ul dir="auto">
<li>
In the root reducer, with reducer updaters.
</li>
</ul>
<p>
Each action is mapped to a reducer updater in kepler.gl. You can import the reducer updater corresponding to a specific action, and call it with the previous state and action payload to get the updated state.<br /> e.g. <code>updateVisDataUpdater</code> is the updater for <code>ActionTypes.UPDATE_VIS_DATA</code> (take a look at each reducer <code>reducers/vis-state.js</code> for action to updater mapping).<br /> Here is an example how you can listen to an app action <code>QUERY_SUCCESS</code> and call <code>updateVisDataUpdater</code> to load data into Kepler.Gl.
</p>
<pre>import keplerGlReducer, {visStateUpdaters} from 'kepler.gl/reducers';
// Root Reducer const reducers =…