leaflet-realtime v2.2.0

Leaflet Realtime

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. Basic example:

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 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: 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 and/or onEachFeature, to customize styling and interaction, as well as adding a listener for the update event, to for example list the features currently visible in the map.

Since version 2.0, Leaflet Realtime uses the 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 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 to false.

API

L.Realtime

This is a realtime updated layer that can be added to the map. It extends L.GeoJSON.

Creation

Options

Provides these options, in addition to the options of L.GeoJSON.

Events

Methods

Source

The source can be one of:

• a string with the URL to get data from
• an options object that is passed to 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(<GeoJSON> features)
• an error callback that should take an error object and an error message (string) as argument: error(<Object> error, <String> message)

UpdateEvent

An update event is fired when the layer's data is updated from its source. The data included loosely resembles D3's join semantics, to make it easy to handle new features (the enter set), updated features (the update set) and removed features (the exit set).