{"id":16043,"library":"gpxparser","title":"GPXParser.js","description":"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.","status":"active","version":"3.0.8","language":"javascript","source_language":"en","source_url":"https://github.com/Luuka/GPXParser.js","tags":["javascript","gpx","parser","GPS","Positioning","GEOJson"],"install":[{"cmd":"npm install gpxparser","lang":"bash","label":"npm"},{"cmd":"yarn add gpxparser","lang":"bash","label":"yarn"},{"cmd":"pnpm add gpxparser","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Provides DOM-related functions polyfill necessary for parsing XML in Node.js environments.","package":"jsdom-nogyp","optional":false}],"imports":[{"note":"The library exports GPXParser as its default export for ESM and TypeScript usage since v3.0.8.","wrong":"import { GPXParser } from 'gpxparser';","symbol":"GPXParser","correct":"import GPXParser from 'gpxparser';"},{"note":"CommonJS import pattern for Node.js environments.","symbol":"GPXParser","correct":"const GPXParser = require('gpxparser');"},{"note":"When included directly via a <script> tag in a browser, GPXParser becomes a global variable.","symbol":"GPXParser (browser global)","correct":"<script src=\"./js/GPXParser.js\"></script>\n// GPXParser is then available globally"}],"quickstart":{"code":"import GPXParser from 'gpxparser';\n\n// A minimal GPX string for demonstration\nconst gpxString = `<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<gpx version=\"1.1\" creator=\"GPXParser.js\">\n  <metadata>\n    <name>Sample Track</name>\n    <desc>A short sample track by GPXParser.js</desc>\n    <author>\n      <name>Acme Corp</name>\n    </author>\n    <time>2023-01-01T12:00:00Z</time>\n  </metadata>\n  <trk>\n    <name>Morning Walk</name>\n    <trkseg>\n      <trkpt lat=\"34.0522\" lon=\"-118.2437\"><ele>100</ele><time>2023-01-01T12:00:00Z</time></trkpt>\n      <trkpt lat=\"34.0535\" lon=\"-118.2500\"><ele>110</ele><time>2023-01-01T12:05:00Z</time></trkpt>\n      <trkpt lat=\"34.0548\" lon=\"-118.2563\"><ele>105</ele><time>2023-01-01T12:10:00Z</time></trkpt>\n    </trkseg>\n  </trk>\n  <wpt lat=\"34.0500\" lon=\"-118.2400\"><name>Starting Point</name></wpt>\n</gpx>`;\n\nconst gpx = new GPXParser();\ngpx.parse(gpxString);\n\nconsole.log('GPX Metadata Name:', gpx.metadata.name);\nconsole.log('Total Tracks Found:', gpx.tracks.length);\nif (gpx.tracks.length > 0) {\n  console.log('First Track Name:', gpx.tracks[0].name);\n  console.log('First Track Total Distance (meters):', gpx.tracks[0].distance.total);\n  console.log('First Track Max Elevation (meters):', gpx.tracks[0].elevation.max);\n}\n\nconsole.log('Total Waypoints Found:', gpx.waypoints.length);\nif (gpx.waypoints.length > 0) {\n  console.log('First Waypoint Name:', gpx.waypoints[0].name);\n}\n\n// Export parsed GPX data to GeoJSON format\nconst geoJSON = gpx.toGeoJSON();\nconsole.log('GeoJSON Output:', JSON.stringify(geoJSON, null, 2));","lang":"typescript","description":"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."},"warnings":[{"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.","message":"Version 3.0.0 introduced significant changes, likely with breaking API modifications. Users upgrading from v2.x should consult the changelog for specific migration steps.","severity":"breaking","affected_versions":">=3.0.0"},{"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.","message":"Prior 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.","severity":"gotcha","affected_versions":"<3.0.5"},{"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`.","message":"The 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.","severity":"gotcha","affected_versions":">=3.0.8"},{"fix":"Always use `import GPXParser from 'gpxparser';` for ESM and TypeScript, as GPXParser is a default export.","message":"While 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.","severity":"gotcha","affected_versions":">=3.0.8"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"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`.","cause":"Attempting to run gpxparser in a Node.js environment without proper DOM polyfills. This was a common issue before v3.0.5.","error":"ReferenceError: document is not defined"},{"fix":"For ESM/TypeScript: `import GPXParser from 'gpxparser';` For CommonJS: `const GPXParser = require('gpxparser');` Then, `const gpx = new GPXParser();`.","cause":"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.","error":"TypeError: gpx.parse is not a function"},{"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.","cause":"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.","error":"Cannot read properties of undefined (reading 'tracks')"},{"fix":"Change the import statement to use the default import syntax: `import GPXParser from 'gpxparser';`.","cause":"Attempting to use a named import (`import { GPXParser }`) for a package that provides a default export.","error":"TS2305: Module '\"gpxparser\"' has no exported member 'GPXParser'. Did you mean to use 'import GPXParser from \"gpxparser\"' instead?"}],"ecosystem":"npm"}