What gpx-export is for

gpx-export converts GPS data into valid GPX 1.1 XML.

It supports:

• generateGpx(track, metadata?) for tracks-only input
• generateGpx(document, metadata?) for full document input
• waypoints, routes, tracks, and metadata
• Garmin TrackPointExtension v2 (gpxtpx) for speed, heart rate, and cadence

Why gpx-export

Many apps collect location points but still need a clean, portable output format for exports, backups, and interoperability with mapping tools.

gpx-export focuses on that narrow problem:

• simple TypeScript-first API
• deterministic XML output order for identical inputs
• no external dependencies
• compatible across Node.js and browser-like runtimes

Features

GPX 1.1 Output

Generates valid GPX 1.1 XML with metadata, routes, tracks, and waypoints.

Garmin TrackPointExtension Support

Supports gpxtpx values on track points (trkpt) for:

• speed
• heart rate
• cadence

Zero Dependencies

No runtime packages required.

Installation

npm install gpx-export

Quick Start

import { generateGpx } from 'gpx-export';

const now = new Date();

const gpx = generateGpx(
  {
    name: 'Morning Ride',
    points: [
      {
        lat: 54.5741,
        lon: -1.318,
        time: now,
        elevation: 32.4,
        speed: 5.2,
      },
    ],
  },
  {
    time: now,
  },
);

console.log(gpx);

Full Document Example

import { generateGpx } from 'gpx-export';

const now = new Date('2026-01-01T12:00:00.000Z');

const gpx = generateGpx({
  metadata: {
    name: 'My Export',
    desc: 'Generated by gpx-export',
    author: { name: 'Chris' },
    link: { href: 'https://github.com/cmyers/gpx-export' },
    time: now,
    keywords: 'gps,gpx,export',
  },
  waypoints: [
    {
      lat: 54.5,
      lon: -1.3,
      name: 'Start',
      time: now,
    },
  ],
  routes: [
    {
      name: 'Route 1',
      points: [
        { lat: 54.5, lon: -1.3, time: now },
        { lat: 54.6, lon: -1.2, time: now },
      ],
    },
  ],
  tracks: [
    {
      name: 'Track 1',
      segments: [
        {
          points: [
            {
              lat: 54.5,
              lon: -1.3,
              time: now,
              elevation: 20.12,
              extensions: {
                speed: 3.45,
                heartRate: 152,
                cadence: 86,
              },
            },
          ],
        },
      ],
    },
  ],
});

API

generateGpx(track: GpxTrack, metadata?: GpxMetadata): string

generateGpx(document: GpxDocument, metadata?: GpxMetadata): string

Generates a GPX 1.1 document from either a GpxTrack or GpxDocument, with optional metadata that shallow-merges into document.metadata.

Supported Types (Summary)

interface GpxPointExtensions {
  speed?: number; // gpxtpx:speed (m/s)
  heartRate?: number; // gpxtpx:hr (bpm)
  cadence?: number; // gpxtpx:cad (rpm)
  rawXml?: string; // trusted XML inside <extensions>
}

interface GpxPoint {
  lat: number;
  lon: number;
  time: Date;
  speed?: number; // legacy alias for extensions.speed
  elevation?: number; // <ele>
  extensions?: GpxPointExtensions;
}

interface GpxTrack {
  name: string;
  createdAt?: Date;
  points?: GpxPoint[];
  segments?: { points: GpxPoint[] }[];
  cmt?: string;
  desc?: string;
  extensions?: GpxPointExtensions;
}

Why speed appears in two places:

• GpxPoint.speed exists for backward compatibility with older callers.
• GpxPoint.extensions.speed is the canonical field for new code.
• When both are provided, extensions.speed wins and only one GPX speed tag is emitted.

All exported type definitions are available from the package root.

Notes

• elevation is formatted to 2 decimal places
• speed is formatted to 4 decimal places
• the Garmin gpxtpx namespace is included when Garmin metrics are present on track points
• Garmin gpxtpx metric tags are emitted on track points (trkpt) only
• rawXml values are inserted as trusted XML and are not escaped
• element output order is deterministic for identical inputs

Testing

Run tests:

npm test

Pull requests are welcome.

License

MIT