a geospatial format parser for Leaflet

npm install leaflet-omnivore
3 downloads in the last day
9 downloads in the last week
19 downloads in the last month

Build Status


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.0.1/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.

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

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
npm install


  • 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.
npm loves you