API Reference

gpx-export exposes a focused, typed API for building GPX 1.1 documents. The main export is generateGpx(...).

generateGpx(...)

Generates GPX 1.1 XML from either: generateGpx(track: GpxTrack, metadata?: GpxMetadata) or generateGpx(document: GpxDocument, metadata?: GpxMetadata). 

import { generateGpx } from "gpx-export";

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

const xml = generateGpx(
  {
    name: "Session",
    points: [{ lat: 54.57, lon: -1.31, time: now }]
  },
  {
    name: "Morning Ride",
    time: now
  }
);

Returns

GpxDocument

interface GpxDocument {
  metadata?: GpxMetadata;
  waypoints?: GpxWaypoint[];
  routes?: GpxRoute[];
  tracks?: GpxTrack[];
}

GpxMetadata

interface GpxMetadata {
  name?: string;
  desc?: string;
  author?: GpxAuthor;
  link?: GpxLink;
  time?: Date;
  keywords?: string;
  copyright?: string | GpxCopyright;
  bounds?: GpxBounds;
}

interface GpxAuthor {
  name: string;
  link?: GpxLink;
}

interface GpxCopyright {
  author: string;
  year?: number;
  license?: string;
}

interface GpxLink {
  href: string;
  text?: string;
  type?: string;
}

GpxPointExtensions

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

GpxPoint

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

Why speed appears in both places: GpxPoint.speed is a legacy compatibility alias, while GpxPoint.extensions.speed is the canonical field for new code. If both are provided, extension speed takes precedence and only one GPX speed tag is emitted.

GpxTrack

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

GpxRoute and GpxWaypoint

interface GpxRoute {
  name?: string;
  cmt?: string;
  desc?: string;
  points: GpxRoutePoint[];
  extensions?: GpxPointExtensions;
}

interface GpxWaypoint {
  lat: number;
  lon: number;
  name?: string;
  cmt?: string;
  desc?: string;
  elevation?: number;
  time?: Date;
  extensions?: GpxPointExtensions;
}

Behavior notes

GitHub ยท npm