This converts KML to GeoJSON, in a browser or with Node.js.
- Dependency-free
- Tiny
- Tested
- Node.js + Browsers
- Rhino
The upstream, well-maintained version is at https://github.com/tmcw/togeojson. If you're considering using this library, you probably should use that one instead. This version is based on an older branch with simpler javascript language dependencies, specifically prepared to be compatible on Rhino.
Convert a KML document to GeoJSON. The first argument, doc
, must be a KML
document as an XML DOM - not as a string. You can get this using jQuery's default
.ajax
function or using a bare XMLHttpRequest with the .response
property
holding an XML DOM.
The output is a Javascript object of GeoJSON data. You can convert it to a string with JSON.stringify or use it directly in libraries like mapbox.js.
Install it into your project with npm install --save togeojson
.
// using togeojson in nodejs
var tj = require('togeojson'),
fs = require('fs'),
// node doesn't have xml parsing or a dom. use xmldom
DOMParser = require('xmldom').DOMParser;
var kml = new DOMParser().parseFromString(fs.readFileSync('foo.kml', 'utf8'));
var converted = tj.kml(kml);
var convertedWithStyles = tj.kml(kml, { styles: true });
- Point
- Polygon
- LineString
- name & description
- ExtendedData
- SimpleData
- MultiGeometry -> GeometryCollection
- Styles with hashing
- Tracks & MultiTracks with
gx:coords
, including altitude - TimeSpan
- TimeStamp
- NetworkLinks
- GroundOverlays
KML's style system isn't semantic: a typical document made through official tools
(read Google) has hundreds of identical styles. So, togeojson does its best to
make this into something usable, by taking a quick hash of each style and exposing
styleUrl
and styleHash
to users. This lets you work backwards from the awful
representation and build your own styles or derive data based on the classes
chosen.
Implied here is that this does not try to represent all data contained in KML styles.
The NetworkLink KML construct allows KML files to refer to other online or local KML files for their content. It's often used to let people pass around files but keep the actual content on servers.
In order to support NetworkLinks, toGeoJSON would need to be asynchronous and perform network requests. These changes would make it more complex and less reliable in order to hit a limited usecase - we'd rather keep it simple and not require users to think about network connectivity and bandwith in order to convert files.
NetworkLink support could be implemented in a separate library as a pre-processing step if desired.
Have a string of XML and need an XML DOM?
var dom = (new DOMParser()).parseFromString(xmlStr, 'text/xml');