Home

Awesome

leaflet-omnivore

Leaflet supports the GeoJSON format by default. What if you have something else? That's where omnivore comes in.

It currently supports:

Omnivore also includes an AJAX library, corslite, so you can specify what you want to add to the map with just a URL.

Installation

use it easily with the Mapbox Plugins CDN:

<script src='//api.tiles.mapbox.com/mapbox.js/plugins/leaflet-omnivore/v0.3.1/leaflet-omnivore.min.js'></script>

Or download leaflet-omnivore.min.js from this repository.

example

Live examples:

var map = L.mapbox.map('map', 'mapbox.streets')
    .setView([38, -102.0], 5);

omnivore.csv('a.csv').addTo(map);
omnivore.gpx('a.gpx').addTo(map);
omnivore.kml('a.kml').addTo(map);
omnivore.wkt('a.wkt').addTo(map);
omnivore.topojson('a.topojson').addTo(map);
omnivore.geojson('a.geojson').addTo(map);
omnivore.polyline('a.txt').addTo(map);

API

Arguments with ? are optional. parser_options consists of options sent to the parser library, not to the layer: if you want to provide options to the layer, see the example in the Custom Layers section.

By default, the library will construct a L.geoJson() layer internally and call .addData(geojson) on it in order to load it full of GeoJSON. If you want to use a different kind of layer, like a L.mapbox.featureLayer(), you can, by passing it as customLayer, as long as it supports events and addData(). You can also use this API to pass custom options to a L.geoJson() instance.:

Valid options:

polyline

Custom Layers

Passing custom options:

var customLayer = L.geoJson(null, {
    filter: function() {
        // my custom filter function
        return true;
    }
});

var myLayer = omnivore.csv('foo', null, customLayer);

Adding custom styles to a GeoJSON layer:

var customLayer = L.geoJson(null, {
    // http://leafletjs.com/reference.html#geojson-style
    style: function(feature) {
        return { color: '#f00' };
    }
});
// this can be any kind of omnivore layer
var runLayer = omnivore.kml('line.kml', null, customLayer)

Using a L.mapbox.featureLayer:

var layer = omnivore.gpx('a.gpx', null, L.mapbox.featureLayer());

Async & Events

Each function returns an L.geoJson object. Functions that load from URLs are asynchronous, so they will not immediately expose accurate .setGeoJSON() functions.

For this reason, we fire events:

var layer = omnivore.gpx('a.gpx')
    .on('ready', function() {
        // when this is fired, the layer
        // is done being initialized
    })
    .on('error', function() {
        // fired if the layer can't be loaded over AJAX
        // or can't be parsed
    })
    .addTo(map);

ready does not fire if you don't use an asynchronous form of the function like .topojson.parse(): because you don't need an event. Just run your code after the call.

Development

This is a browserify project:

git clone git@github.com:mapbox/leaflet-omnivore.git

cd leaflet-omnivore

# to run tests
npm install

# to build leaflet-omnivore.js
npm run prepublish

leaflet-omnivore.js and leaflet-omnivore.min.js are built files generated from index.js by browserify. If you find an issue, it either needs to be fixed in index.js, or in one of the libraries leaflet-omnivore uses to parse formats.

FAQ