Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/mapbox/togeojson

convert KML and GPX to GeoJSON, without the fuss
https://github.com/mapbox/togeojson

Last synced: 20 days ago
JSON representation

convert KML and GPX to GeoJSON, without the fuss

Host: GitHub
URL: https://github.com/mapbox/togeojson
Owner: mapbox
License: bsd-2-clause
Created: 2012-12-08T04:17:57.000Z (almost 12 years ago)
Default Branch: master
Last Pushed: 2024-04-09T17:19:02.000Z (7 months ago)
Last Synced: 2024-10-13T05:42:50.210Z (22 days ago)
Language: JavaScript
Homepage: http://mapbox.github.io/togeojson/
Size: 5.12 MB
Stars: 1,269
Watchers: 153
Forks: 326
Open Issues: 30
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE

Awesome Lists containing this project

awesome-starred - mapbox/togeojson - convert KML and GPX to GeoJSON, without the fuss (others)

README

        [![Build status](https://img.shields.io/travis/mapbox/togeojson.svg "Build status")](http://travis-ci.org/mapbox/togeojson)

[![Coverage status](https://img.shields.io/coveralls/mapbox/togeojson.svg "Coverage status")](https://coveralls.io/r/mapbox/togeojson)

[![stable](http://badges.github.io/stability-badges/dist/stable.svg)](http://github.com/badges/stability-badges)

[![FOSSA Status](https://app.fossa.io/api/projects/git%2Bhttps%3A%2F%2Fgithub.com%2Fmapbox%2Ftogeojson.svg?type=shield)](https://app.fossa.io/projects/git%2Bhttps%3A%2F%2Fgithub.com%2Fmapbox%2Ftogeojson?ref=badge_shield)

# Convert KML and GPX to GeoJSON.

This converts [KML](https://developers.google.com/kml/documentation/) & [GPX](http://www.topografix.com/gpx.asp)

to [GeoJSON](http://www.geojson.org/), in a browser or with [Node.js](http://nodejs.org/).

* [x] Tiny

* [x] Tested

* [x] Node.js + Browsers

Want to use this with [Leaflet](http://leafletjs.com/)? Try [leaflet-omnivore](https://github.com/mapbox/leaflet-omnivore)!

## 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](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify)

or use it directly in libraries like [mapbox.js](http://www.mapbox.com/mapbox.js/).

### `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.

## CLI

Install it into your path with `npm install -g @mapbox/togeojson`.

```

~> togeojson file.kml > file.geojson

```

## Node.js

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

```javascript

// using togeojson in nodejs

var tj = require('@mapbox/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 });

```

## Browser

Download it into your project like

    wget https://raw.githubusercontent.com/mapbox/togeojson/master/togeojson.js

```html

$.ajax('test/data/linestring.kml').done(function(xml) {

    console.log(toGeoJSON.kml(xml));

});

```

toGeoJSON doesn't include AJAX - you can use [jQuery](http://jquery.com/) for

just AJAX.

### 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](https://developers.google.com/kml/documentation/kmlreference#timespan)

* [x] [TimeStamp](https://developers.google.com/kml/documentation/kmlreference#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

### 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 bandwidth

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?

```js

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

```

## License

[![FOSSA Status](https://app.fossa.io/api/projects/git%2Bhttps%3A%2F%2Fgithub.com%2Fmapbox%2Ftogeojson.svg?type=large)](https://app.fossa.io/projects/git%2Bhttps%3A%2F%2Fgithub.com%2Fmapbox%2Ftogeojson?ref=badge_large)