Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/perliedman/leaflet-realtime
Put realtime data on a Leaflet map
https://github.com/perliedman/leaflet-realtime
Last synced: about 1 month ago
JSON representation
Put realtime data on a Leaflet map
- Host: GitHub
- URL: https://github.com/perliedman/leaflet-realtime
- Owner: perliedman
- License: isc
- Created: 2014-10-15T20:42:48.000Z (about 10 years ago)
- Default Branch: master
- Last Pushed: 2022-11-17T15:34:59.000Z (almost 2 years ago)
- Last Synced: 2024-10-09T08:37:20.215Z (about 1 month ago)
- Language: JavaScript
- Size: 364 KB
- Stars: 738
- Watchers: 46
- Forks: 167
- Open Issues: 15
-
Metadata Files:
- Readme: README.md
- License: LICENSE.md
Awesome Lists containing this project
README
# Leaflet Realtime
[](https://travis-ci.org/perliedman/leaflet-realtime)
[](https://www.npmjs.com/package/leaflet-realtime) 
[](https://cdnjs.com/libraries/leaflet-realtime) [](https://greenkeeper.io/)
Put realtime data on a Leaflet map: live tracking GPS units, sensor data or just about anything.
_Note:_ version 2 and up of this plugin is _only compatible with Leaflet 1.0 and later. Use earlier versions of Leaflet Realtime if you need Leaflet 0.7 compatibility.
## Example
Checkout the [Leaflet Realtime Demo](http://www.liedman.net/leaflet-realtime). Basic example:
```javascript
var map = L.map('map'),
realtime = L.realtime({
url: 'https://wanderdrone.appspot.com/',
crossOrigin: true,
type: 'json'
}, {
interval: 3 * 1000
}).addTo(map);
realtime.on('update', function() {
map.fitBounds(realtime.getBounds(), {maxZoom: 3});
});
```
## Usage
### Overview
By default, Leaflet Realtime reads and displays GeoJSON from a provided source. A "source" is usually a URL, and data can be fetched using AJAX (XHR), JSONP. This means Leaflet Realtime will _poll_ for data, pulling it from the source. Alternatively, you can write your own source, to provide data in just about any way you want. Leaflet Realtime can also be made work with _push_ data, for example data pushed from the server using [socket.io](http://socket.io/) or similar.
To be able to figure out when new features are added, when old features are removed, and which features are just updated, Leaflet Realtime needs to identify each feature uniquely. This is done using a _feature id_. Usually, this can be done using one of the feature's `properties`. By default, Leaflet Realtime will try to look for a called property `id` and use that.
By default, `L.Realtime` uses a `L.GeoJSON` layer to display the results. You can basically do anything you can do with `L.GeoJSON` with `L.Realtime` - styling, `onEachFeature`, gettings bounds, etc. as if you were working directly with a normal GeoJSON layer.
`L.Realtime` can also use other layer types to display the results, for example it can use a `MarkerClusterGroup` from [Leaflet MarkerCluster](https://github.com/Leaflet/Leaflet.markercluster): pass a `LayerGroup` (or any class that implements `addLayer` and `removeLayer`) to `L.Realtime`'s `container` option. (This feature was added in version 2.1.0.)
Typical usage involves instantiating `L.Realtime` with options for [`style`](http://leafletjs.com/reference.html#geojson-style) and/or [`onEachFeature`](http://leafletjs.com/reference.html#geojson-oneachfeature), to customize styling and interaction, as well as adding a listener for the [`update`](#event-update) event, to for example list the features currently visible in the map.
Since version 2.0, Leaflet Realtime uses the [Fetch API](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API) to request data (AJAX). If you are in the unfortunate situation that you need to support a browser without Fetch, you either need to use a polyfill, or write your own [source function](#source) to make the AJAX requests.
### Push data
If you prefer getting data _pushed_ from the server, in contrast to Leaflet Realtime pulling it with a standard HTTP request, you can feed added and updated GeoJSON data to Leaflet Realtime using the `update` method. In this scenario, you will also need to remove features by explicit calls to `remove`.
Since automatic updates do not make sense in a push scenario, you want to create the layer with the option `start` set to `false`.
### API
#### L.Realtime
This is a realtime updated layer that can be added to the map. It extends [L.GeoJSON](http://leafletjs.com/reference.html#geojson).
##### Creation
Factory | Description
-----------------------|-------------------------------------------------------
`L.Realtime(<`[`Source`](#source)`> source, <`[`RealtimeOptions`](#realtimeoptions)`> options?)` | Instantiates a new realtime layer with the provided source and options
Provides these options, in addition to the options of [`L.GeoJSON`](http://leafletjs.com/reference.html#geojson).
Option | Type | Default | Description
-----------------------|---------------------|----------------------|---------------------------------------------------------
`start` | `Boolean` | `true` | Should automatic updates be enabled when layer is added on the map and stopped when layer is removed from the map
`interval` | `Number` | 60000 | Automatic update interval, in milliseconds
`getFeatureId( featureData)` | `Function` | Returns `featureData.properties.id` | Function used to get an identifier uniquely identify a feature over time
`updateFeature( featureData, oldLayer)` | `Function` | Special | Used to update an existing feature's layer; by default, points (markers) are updated, other layers are discarded and replaced with a new, updated layer. Allows to create more complex transitions, for example, when a feature is updated |
`container` | `LayerGroup` | L.geoJson() | Specifies the layer instance to display the results in
`removeMissing` | `Boolean` | `false` | Should missing features between updates been automatically removed from the layer
##### Events
Event | Data | Description
--------------|----------------|---------------------------------------------------------------
`update` | [`UpdateEvent`](#updateevent) | Fires when the layer's data is updated
##### Methods
Method | Returns | Description
-----------------------|----------------|-----------------------------------------------------------------
`start()` | `this` | Starts automatic updates
`stop()` | `this` | Stops automatic updates
`isRunning()` | `Boolean` | Tells if automatic updates are running
`update( featureData?)` | `this` | Updates the layer's data. If `featureData` is provided, it is used to add or update data in the layer, otherwise the layer's source is queried for new data asynchronously
`remove( featureData)` | `this` | Removes the provided feature or features from the layer
`getLayer( featureId)` | `ILayer` | Retrieves the layer used for a certain feature
`getFeature( featureId)` | `GeoJSON` | Retrieves the feature data for the given `featureId`
The source can be one of:
* a string with the URL to get data from
* an options object that is passed to [fetch](https://developer.mozilla.org/en-US/docs/Web/API/WindowOrWorkerGlobalScope/fetch) for fetching the data
* a function in case you need more freedom.
In case you use a function, the function should take two callbacks as arguments: `fn(success, error)`, with the callbacks:
* a success callback that takes GeoJSON as argument: `success( features)`
* an error callback that should take an error object and an error message (string) as argument: `error( error, message)`
An update event is fired when the layer's data is updated from its source. The data included loosely resembles D3's [join semantics](http://bost.ocks.org/mike/join/), to make it easy to handle new features (the _enter_ set), updated features (the _update_ set) and removed features (the _exit_ set).
property | type | description
--------------|------------|-----------------------------------
`features` | Object | Complete hash of current features, with feature id as key
`enter` | Object | Features added by this update, with feature id as key
`update` | Object | Existing features updated by this update, with feature id as key
`exit` | Object | Existing features that were removed by this update, with feature id as key