a geospatial format parser for Leaflet

npm install leaflet-omnivore
4 downloads in the last week
11 downloads in the last month


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

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


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



  • .csv(url, options?): 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): 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): Load GeoJSON file at URL, parse GeoJSON, and return layer.
  • .wkt(url): Load & parse WKT, and return layer.
  • .wkt.parse(wktString): Parse WKT, and return layer.
  • .topojson(url): Load & parse TopoJSON, and return layer.
  • .topojson.parse(topojson): Parse TopoJSON (given as a string or object), and return layer.

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