npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

@rustyconover/togeojson

v3.0.2

Published

convert KML and GPX to GeoJSON

Downloads

2

Readme

Convert KML and GPX to GeoJSON.

CircleCI

:sparkles: This is a maintained and modernized fork of the toGeoJSON project, which I (Tom) wrote while at Mapbox, and am now maintaining on a personal basis because the Mapbox-owned project is abandoned.

This converts KML & GPX to GeoJSON, in a browser or with Node.js.

  • [x] Dependency-free
  • [x] Tiny
  • [x] Tested
  • [x] Node.js + Browsers

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

API

toGeoJSON.kml(doc)

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.

toGeoJSON.kmlGen(doc)

Convert KML to GeoJSON incrementally, returning a Generator that yields output feature by feature.

toGeoJSON.gpx(doc)

Convert a GPX document to GeoJSON. The first argument, doc, must be a GPX 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, same as .kml outputs.

toGeoJSON.gpxGen(doc)

Convert GPX to GeoJSON incrementally, returning a Generator that yields output feature by feature.

CLI

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

Node.js

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

// using togeojson in nodejs

const tj = require("@tmcw/togeojson");
const fs = require("fs");
// node doesn't have xml parsing or a dom. use xmldom
const DOMParser = require("xmldom").DOMParser;

const kml = new DOMParser().parseFromString(fs.readFileSync("foo.kml", "utf8"));

const converted = tj.kml(kml);

const convertedWithStyles = tj.kml(kml, { styles: true });

Browser

<script type="module">
  import { kml } from "https://unpkg.com/@tmcw/togeojson?module";

  fetch("test/data/linestring.kml")
    .then(function(response) {
      return response.xml();
    })
    .then(function(xml) {
      console.log(kml(xml));
    });
</script>

KML Feature Support

  • [x] Point
  • [x] Polygon
  • [x] LineString
  • [x] name & description
  • [x] ExtendedData
  • [x] SimpleData
  • [x] MultiGeometry -> GeometryCollection
  • [x] Styles with hashing
  • [x] Tracks & MultiTracks with gx:coords, including altitude
  • [x] TimeSpan
  • [x] TimeStamp
  • [ ] NetworkLinks
  • [ ] GroundOverlays

GPX Feature Support

  • [x] Line Paths
  • [x] Line styles
  • [ ] Properties
    • [x] 'name', 'cmt', 'desc', 'link', 'time', 'keywords', 'sym', 'type' tags
    • [ ] 'author', 'copyright' tags

FAQ

How does this differ from mapbox/togeojson?

  • It’s available as an ES Module. If you're using a modern JavaScript bundler or using ES Modules in the browser, this makes it a bit more efficient and sometimes easier to use.
  • Conversion methods are available as generators, which makes the conversion of big files more efficient.
  • The command line utility was moved to tmcw/togeojson-cli, which lets this module enjoy reduced dependencies: installing @tmcw/togeojson doesn’t require any other dependencies.
  • The hashing method is improved, which means that parsing is the same between browsers and Node.js, and there are no runtime dependencies.

What is hashing?

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.

Why doesn't toGeoJSON support NetworkLinks?

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.

Should toGeoJSON support feature X from KML?

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

KML is a very complex format with many features. Some of these features, like NetworkLinks, folders, and GroundOverlays, don't have a GeoJSON equivalent. In these cases, toGeoJSON doesn't convert the features. It also doesn't crash on these constructs: toGeoJSON should be able to run on all valid KML and GPX files without crashing: but for some files it may have no output.

We encourage other libraries to look into supporting these features, but support for them is out of scope for toGeoJSON.

Protips:

Have a string of XML and need an XML DOM?

var dom = new DOMParser().parseFromString(xmlStr, "text/xml");