It currently supports:
- CSV (via csv2geojson)
- GPX (via toGeoJSON)
- KML (via toGeoJSON)
- WKT (via wellknown)
- 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:
leaflet-omnivore.min.js from this repository.
var map = Lmapbox;omnivore;omnivore;omnivore;omnivore;omnivore;omnivore;omnivore;
? 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
.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
You can also use this API to pass custom options to a
.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.
precisionwill 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;var myLayer = omnivore;
Adding custom styles to a GeoJSON layer:
var customLayer = L;// this can be any kind of omnivore layervar runLayer = omnivore
var layer = omnivore;
Async & Events
Each function returns an
L.geoJson object. Functions that load from URLs
are asynchronous, so they will not immediately expose accurate
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;
ready does not fire if you don't use an asynchronous form of the function
.topojson.parse(): because you don't need an event. Just run your code
after the call.
This is a browserify project:
git clone email@example.com:mapbox/leaflet-omnivore.gitcd leaflet-omnivore# to run testsnpm install# to build leaflet-omnivore.jsnpm run build
leaflet-omnivore.min.js are built files generated
browserify. If you find an issue, it either needs to be
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.