gpxparser

library3.0.8jsnpmunverified

GPXParser.js is a JavaScript library designed for parsing .gpx (GPS Exchange Format) files, which are XML-based data structures for GPS information. It extracts core GPX data like metadata, waypoints, tracks, and routes, and further computes various derived metrics such as total and cumulative distances, minimum, maximum, average, positive, and negative elevation differences, and segment slopes. The current stable version is 3.0.8, actively maintained with regular patch releases addressing bug fixes and minor feature enhancements. A key differentiator is its ability to not only parse but also process the geographical data for insights, and export the parsed data into GeoJSON format, making it suitable for modern web mapping applications. It includes built-in polyfills for DOM functionalities, enabling its use in Node.js environments without manual setup since version 3.0.5.

data serialization

npm install gpxparser

github ↗package ↗

INSTALL

IMPORT

SIG · GPXPARSER

gpxparser

datajavascriptv3.0.8

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

GPXParser

✓ import GPXParser from 'gpxparser';

✗ import { GPXParser } from 'gpxparser';

The library exports GPXParser as its default export for ESM and TypeScript usage since v3.0.8.

GPXParser

✓ const GPXParser = require('gpxparser');

CommonJS import pattern for Node.js environments.

GPXParser (browser global)

✓ <script src="./js/GPXParser.js"></script> // GPXParser is then available globally

When included directly via a <script> tag in a browser, GPXParser becomes a global variable.

This quickstart demonstrates how to instantiate GPXParser, parse a sample GPX string, access its metadata, tracks, and waypoints, and export the processed data to GeoJSON.

import GPXParser from 'gpxparser'; // A minimal GPX string for demonstration const gpxString = `<?xml version="1.0" encoding="UTF-8"?> <gpx version="1.1" creator="GPXParser.js"> <metadata> <name>Sample Track</name> <desc>A short sample track by GPXParser.js</desc> <author> <name>Acme Corp</name> </author> <time>2023-01-01T12:00:00Z</time> </metadata> <trk> <name>Morning Walk</name> <trkseg> <trkpt lat="34.0522" lon="-118.2437"><ele>100</ele><time>2023-01-01T12:00:00Z</time></trkpt> <trkpt lat="34.0535" lon="-118.2500"><ele>110</ele><time>2023-01-01T12:05:00Z</time></trkpt> <trkpt lat="34.0548" lon="-118.2563"><ele>105</ele><time>2023-01-01T12:10:00Z</time></trkpt> </trkseg> </trk> <wpt lat="34.0500" lon="-118.2400"><name>Starting Point</name></wpt> </gpx>`; const gpx = new GPXParser(); gpx.parse(gpxString); console.log('GPX Metadata Name:', gpx.metadata.name); console.log('Total Tracks Found:', gpx.tracks.length); if (gpx.tracks.length > 0) { console.log('First Track Name:', gpx.tracks[0].name); console.log('First Track Total Distance (meters):', gpx.tracks[0].distance.total); console.log('First Track Max Elevation (meters):', gpx.tracks[0].elevation.max); } console.log('Total Waypoints Found:', gpx.waypoints.length); if (gpx.waypoints.length > 0) { console.log('First Waypoint Name:', gpx.waypoints[0].name); } // Export parsed GPX data to GeoJSON format const geoJSON = gpx.toGeoJSON(); console.log('GeoJSON Output:', JSON.stringify(geoJSON, null, 2));

Debug

Known issues

breakingVersion 3.0.0 introduced significant changes, likely with breaking API modifications. Users upgrading from v2.x should consult the changelog for specific migration steps.

fix

Review the official release notes and migration guides for gpxparser v3 to adapt your code. Re-test all GPX parsing and data access logic.

affects: >=3.0.0

gotchaPrior to v3.0.5, running GPXParser in Node.js environments required manual polyfills for DOM-related functions (e.g., XMLHttpRequest, DOMParser). Without these, parsing would fail.

fix

Upgrade to v3.0.5 or newer, which includes `jsdom-nogyp` as a dependency to provide these polyfills automatically. If upgrading isn't possible, manually include a DOM polyfill library.

affects: <3.0.5

gotchaThe package size was reduced in v3.0.8 by removing documentation and demo files directly from the npm package. These resources are now only available on the GitHub repository.

fix

Access documentation and demos directly from the project's GitHub repository (github.com/Luuka/GPXParser.js) rather than looking for them in `node_modules`.

affects: >=3.0.8

gotchaWhile v3.0.8 adds TypeScript support, incorrect import statements (e.g., named import for a default export) can lead to compilation errors or runtime issues.

fix

Always use `import GPXParser from 'gpxparser';` for ESM and TypeScript, as GPXParser is a default export.

affects: >=3.0.8

Errors

Common errors & fixes

ReferenceError: document is not defined

Attempting to run gpxparser in a Node.js environment without proper DOM polyfills. This was a common issue before v3.0.5.

fix

Ensure you are using `gpxparser` v3.0.5 or newer, which bundles necessary polyfills. If not, upgrade or manually provide a DOM polyfill like `jsdom`.

TypeError: gpx.parse is not a function

The `GPXParser` object was not correctly instantiated or imported. This often happens with incorrect CommonJS `require` or ESM `import` syntax, or if the global `GPXParser` variable is not set up correctly in a browser.

fix

For ESM/TypeScript: `import GPXParser from 'gpxparser';` For CommonJS: `const GPXParser = require('gpxparser');` Then, `const gpx = new GPXParser();`.

Cannot read properties of undefined (reading 'tracks')

This error occurs when attempting to access properties like `gpx.tracks` or `gpx.waypoints` before the `parse()` method has been successfully called, or if the provided GPX string is malformed/empty and parsing failed to populate these properties.

fix

Always call `gpx.parse(gpxString)` with a valid GPX XML string before attempting to access parsed data properties. Add error handling around `parse()` if the input string might be invalid.

TS2305: Module '"gpxparser"' has no exported member 'GPXParser'. Did you mean to use 'import GPXParser from "gpxparser"' instead?

Attempting to use a named import (`import { GPXParser }`) for a package that provides a default export.

fix

Change the import statement to use the default import syntax: `import GPXParser from 'gpxparser';`.

Upgrade

Version history

3.0.8latest on npm

Audit

Dependencies

jsdom-nogyprequiredProvides DOM-related functions polyfill necessary for parsing XML in Node.js environments.

Agent activity

8 hits · last 30 days

node

Resources

githubhttps://github.com/Luuka/GPXParser.js ↗

packagehttps://www.npmjs.com/package/gpxparser ↗