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.3.1/leaflet-omnivore.min.js'></script>
Or download leaflet-omnivore.min.js
from this repository.
Live examples:
var map = L.mapbox.map('map', 'mapbox.streets') .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); omnivore.polyline('a.txt').addTo(map);
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, { filter: function() { // 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 style: function(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 layererror
: fired if data can't be loaded or parsedvar 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.
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 prepublish
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.