leaflet-omnivore

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

It currently supports:

• CSV (via csv2geojson)
• GPX (via toGeoJSON)
• KML (via toGeoJSON)
• WKT (via wellknown)
• TopoJSON

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.1.2/leaflet-omnivore.min.js'></script>

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

example

Live examples:

• WKT
• TopoJSON
• Tooltips
• KML
• GPX
• Icons
• CSV

var map = L.mapbox.map('map', 'examples.map-9ijuk24y')
    .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);

api

Arguments with ? are optional.

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

• .csv(url, options?, customLayer?): Load & parse CSV, and return layer. Options are the same as csv2geojson: latfield, lonfield, delimiter
• .csv.parse(csvString, options?): Parse CSV, and return layer.
• .kml(url): Load & parse KML, and return layer.
• .kml.parse(kmlString | gpxDom): Parse KML from a string of XML or XML DOM, and return layer.
• .gpx(url, options?, customLayer?): Load & parse GPX, and return layer.
• .gpx.parse(gpxString | gpxDom): Parse GPX from a string of XML or XML DOM, and return layer.
• .geojson(url, options?, customLayer?): Load GeoJSON file at URL, parse GeoJSON, and return layer.
• .wkt(url, options?, customLayer?): Load & parse WKT, and return layer.
• .wkt.parse(wktString): Parse WKT, and return layer.
• .topojson(url, options?, customLayer?): Load & parse TopoJSON, and return layer.
• .topojson.parse(topojson): Parse TopoJSON (given as a string or object), and return layer.

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);

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:

• ready: fired when all data is loaded into the layer
• error: fired if data can't be loaded or parsed

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 build

FAQ

• What if I just want one format? Lucky for you, each format is specified in a different module, so you can just use TopoJSON, csv2geojson, wellknown, or toGeoJSON individually.
• My AJAX request is failing for a cross-domain request. Read up on the Same Origin Restriction. By default, we use corslite, so cross-domain requests will try to use CORS if your server and browser supports it, but if one of them doesn't, there's no way on the internet to support your request.
• Why isn't JSONP supported? Here's why.