Leaflet supports the GeoJSON format by default. What if you have something else? That's where omnivore comes in.
It currently supports:
- CSV (via csv2geojson)
- GPX (via toGeoJSON)
- KML (via toGeoJSON)
- WKT (via wellknown)
- TopoJSON
- Encoded Polylines via polyline
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', '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 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.
This is a browserify project:
git clone [email protected]: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.