@we-gold/gpxjs v1.0.8

GPX.JS

Based on GPXParser.js, which has been unmaintained, this updated library is intended to bring modern JavaScript features to GPX parsing, including extensions in tracks and fully featured typescript support.

I'm also open to any improvements or suggestions with the library, so feel free to leave an issue (Contributing).

GPX Schema

The schema for GPX, a commonly used gps tracking format, can be found here: GPX 1.1.

See Documentation for more details on how GPX data is represented by the library.

Usage

This library does include support for non-browser execution.

Right now, to use this in Node.js without a browser or in something like React Native, use xmldom-qsa instead.

See instructions below on how to use a custom DOM parser.

Install using NPM

npm i @we-gold/gpxjs

Then, import the parseGPX method:

import { parseGPX } from "@we-gold/gpxjs"

const [parsedFile, error] = parseGPX(myXMLGPXString)

// Or use a try catch to verify
if (error) throw error

const geojson = parsedFile.toGeoJSON()

Include JavaScript File

In an HTML document:

<script src="./src/gpxjs.js"></script>

<script type="module">
	import { parseGPX } from "@we-gold/gpxjs"

	const [parsedFile, error] = parseGPX(myXMLGPXString)

	// Or use a try catch to verify
	if (error) throw error

	const geojson = parsedFile.toGeoJSON()
</script>

Fetching a GPX File

While this feature isn't included, it is fairly simple to fetch a GPX file and format it as a string.

import { parseGPX } from "@we-gold/gpxjs"

fetch("./somefile.gpx")
	.then((response) => {
		if (!response.ok) {
			throw new Error("Failed to fetch the file")
		}
		return response.text()
	})
	.then((data) => {
		const [parsedFile, error] = parseGPX(data)

		// Or use a try catch to verify
		if (error) throw error

		const geojson = parsedFile.toGeoJSON()
	})

Use the Parsed GPX

const totalDistance = gpx.tracks[0].distance.total

const extensions = gpx.tracks[1].extensions

Export to GeoJSON

const geoJSON = parsedGPX.toGeoJSON()

Using a Custom DOM Parser

If working in an environment where a custom DOM Parser is required, you can include it like so:

Note, this is significantly slower than using the browser parser.

import { parseGPXWithCustomParser } from "@we-gold/gpxjs"
import { DOMParser } from "xmldom-qsa"

const customParseMethod = (txt: string): Document | null => {
	return new DOMParser().parseFromString(txt, "text/xml")
}

const [parsedFile, error] = parseGPXWithCustomParser(
	myXMLGPXString,
	customParseMethod
)

Contribution

If you are having an issue and aren't sure how to resolve it, feel free to leave an issue.

If you do know how to fix it, please leave a PR, as I cannot guarantee how soon I can address the issue myself.

I do try to be responsive to PRs though, so if you leave one I'll try to get it merged asap.

Also, there are some basic tests built in to the library, so please test your code before you try to get it merged (just to make sure everything is backwards compatible). Use npm run test to do this.

Documentation

These descriptions are adapted from GPXParser.js, with minor modifications.

For specific type definition, see types.ts.

Metadata

Waypoint

Track

Route

Point

Distance

Elevation

Author

Email

Link