Repository files navigation

togeojson development is supported by 🌎placemark.io

This convertsKML,TCX, &GPXtoGeoJSON, in a browser or withNode.js.

• Dependency-free
• Tiny
• Tested
• Node.js + Browsers

This is a JavaScript library that lets projects convert KML and GPX to GeoJSON. If you'relooking for a command line too, use@tmcw/togeojson-cli. If youwant to convert one KML or GPX file, usemy online tool.If you want to convert another format, considerGDAL.

In addition to converting KML’s<ExtendedData> verbatim, @tmcw/togeojsonalso encodes parts of KML, GPX, and TCX files that otherwise would be lost.

KML

• Style properties:fill-color,fill-opacity,stroke,stroke-opacity,icon-color,icon-opacity,label-color,label-opacity,icon-scale,icon-heading,icon-offset,icon-offset-units

GPX

• Style properties:stroke,stroke-opacity,stroke-width

TCX

• Line properties:totalTimeSeconds,distanceMeters,maxSpeed,avgHeartRate,maxHeartRate,avgSpeed,avgWatts,maxWatts

This also emits thegeojson-coordinate-properties formatto include time and other attributes that apply to each coordinate of a LineString.

Example of working with Ground Overlays in Mapbox GL JS

KML GroundOverlays are now supported, and transformed into Featureswith Polygon geometries. They have two defined properties:

{"@geometry-type":"groundoverlay","icon":"https://url.to.image…"}

Bothgx:LatLonQuad andLatLonBox-based ground overlays are supported.

If you're using this with TypeScript, you'll want to also install:

• @types/geojson
• @xmldom/xmldom

These will give you accurate types for both input and outputtypes. Due to TypeScript limitations, it's currently necessaryto install@xmldom/xmldom for accurate input types evenif you aren't using that module for parsing XML.If you have ideas for how to improve this, pleasecomment on this PR!.

Use@tmcw/togeojson-cli to use thissoftware as a command-line tool.

Install it into your project withnpm install --save @tmcw/togeojson.

// using togeojson in nodejsconsttj=require("@tmcw/togeojson");constfs=require("fs");// node doesn't have xml parsing or a dom. use xmldomconstDOMParser=require("xmldom").DOMParser;constkml=newDOMParser().parseFromString(fs.readFileSync("foo.kml","utf8"));constconverted=tj.kml(kml);

// The ES Module provides named exports, to import kml, gpx,// and other parts of the module by name.import{kml}from"@tmcw/togeojson";

<scripttype="module">import{kml}from"https://unpkg.com/@tmcw/togeojson?module";fetch("test/data/linestring.kml").then(function(response){returnresponse.text();}).then(function(xml){console.log(kml(newDOMParser().parseFromString(xml,"text/xml")));});</script>

• Point
• Polygon
• LineString
• name & description
• ExtendedData
• SimpleData
• MultiGeometry -> GeometryCollection
• Styles
• Tracks & MultiTracks withgx:coords, including altitude
• TimeSpan
• TimeStamp
• Folders (with kmlWithFolders)
• GroundOverlays
• NetworkLinks

• Line Paths
• Line styles
• Properties
  • 'name', 'cmt', 'desc', 'link', 'time', 'keywords', 'sym', 'type' tags
  • gpxx Garmin extensions on tracks and routes
  • 'author', 'copyright' tags

• This repository is maintained.
• It’s available as an ES Module. If you're using a modern JavaScript bundler orusing ES Modules in the browser, this makes it a bit more efficient and sometimeseasier to use.
• Conversion methods are available as generators, which makes the conversion of bigfiles more efficient.
• The command line utility was moved totmcw/togeojson-cli,which lets this module enjoy reduced dependencies: installing @tmcw/togeojson doesn’trequire any other dependencies.

The NetworkLink KML construct allows KML files to refer to other onlineor local KML files for their content. It's often used to let people pass aroundfiles but keep the actual content on servers.

In order to support NetworkLinks, toGeoJSON would need to be asynchronousand perform network requests. These changes would make it more complex and lessreliable in order to hit a limited usecase - we'd rather keep it simpleand not require users to think about network connectivity and bandwithin order to convert files.

NetworkLink support could be implemented in a separate library as a pre-processingstep if desired.

This module should support converting all KML and GPX features that have commonplaceequivalents in GeoJSON.

Have a string of XML and need an XML DOM? There are two main options:

• Usexmldom, a JavaScript module that contains its own XML parser
• UseDOMParser, the native platform XML parser

We recommend thatyou use xmldom, not the platform. DOMParser requires XML to be valid, which means that any XML namespaces that a KML, GPX, or TCX file contains are valid. A lot of existing data is invalid XML, and will be parsed only in part by DOMParser, but can be fully parsed by xmldom.

Using xmldom (recommended):

constxmldom=require("@xmldom/xmldom");constdom=newxmldom.DOMParser().parseFromString(xmlStr,"text/xml");

Using DOMParser:

vardom=newDOMParser().parseFromString(xmlStr,"text/xml");