a geospatial format parser for Leaflet


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.

use it easily with the Mapbox Plugins CDN:

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

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

Live examples:

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

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

  • .csv(url, parser_options?, customLayer?): Load & parse CSV, and return layer. Options are the same as csv2geojson: latfield, lonfield, delimiter
  • .csv.parse(csvString, parser_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, parser_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, parser_options?, customLayer?): Load GeoJSON file at URL, parse GeoJSON, and return layer.
  • .wkt(url, parser_options?, customLayer?): Load & parse WKT, and return layer.
  • .wkt.parse(wktString): Parse WKT, and return layer.
  • .topojson(url, parser_options?, customLayer?): Load & parse TopoJSON, and return layer.
  • .topojson.parse(topojson): Parse TopoJSON (given as a string or object), and return layer.
  • .polyline(url, parser_options?, customLayer?): Load & parse polyline, and return layer.
  • .polyline.parse(txt, options, layer): Parse polyline (given as a string or object), and return layer.

Valid options:

  • precision will change how the polyline is interpreted. By default, the value is 5. This is the factor in the algorithm, by default 1e5, which is adjustable.

Passing custom options:

var customLayer = L.geoJson(null, {
    filterfunction() {
        // 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 
    stylefunction(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());

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 

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.

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

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.

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