leaflet-omnivore

a geospatial format parser for Leaflet

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

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

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

example

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

  • .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
    })
    .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
npm install
make

FAQ

  • 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