Examples

gpx-export can be used anywhere you need portable GPX 1.1 exports. These examples show common generation flows with the current API.

Basic one-point track export

Useful for smoke tests and validating end-to-end export wiring.

import { generateGpx } from "gpx-export";

const now = new Date("2026-03-23T09:00:00Z");

const gpx = generateGpx(
  {
    name: "Quick Point",
    points: [
      {
        lat: 54.57,
        lon: -1.31,
        time: now
      }
    ]
  },
  { name: "Quick Point", time: now }
);

Multi-point run with Garmin metrics

Garmin extension output is included when Garmin metrics are present on track points.

const gpx = generateGpx({
  name: "Interval Session",
  segments: [
    {
      points: [
        {
          lat: 54.5741,
          lon: -1.3180,
          time: new Date("2026-03-23T07:15:00Z"),
          elevation: 32.4,
          extensions: {
            speed: 5.2,
            heartRate: 151,
            cadence: 86
          }
        },
        {
          lat: 54.5751,
          lon: -1.3194,
          time: new Date("2026-03-23T07:16:00Z"),
          elevation: 34.0,
          speed: 5.6
        }
      ]
    }
  ]
});

Waypoints and routes

Build complete GPX documents with waypoint and route data.

const gpx = generateGpx({
  waypoints: [
    { lat: 54.57, lon: -1.31, name: "Start", time: new Date() }
  ],
  routes: [
    {
      name: "Scenic Route",
      points: [
        { lat: 54.57, lon: -1.31, time: new Date() },
        { lat: 54.59, lon: -1.28, time: new Date() }
      ]
    }
  ]
});

Using optional metadata merge

generateGpx(document, metadata?) accepts optional metadata that shallow-merges into document.metadata.

import { generateGpx } from "gpx-export";

const gpx = generateGpx(
  {
    tracks: [
      {
        name: "Session",
        points: [{ lat: 54.57, lon: -1.31, time: new Date() }]
      }
    ]
  },
  {
    name: "Morning Ride",
    time: new Date(),
    keywords: "cycling,training"
  }
);

Mapping app sensor samples

Convert your own schema into typed track points.

const points = samples.map((sample) => ({
  lat: sample.latitude,
  lon: sample.longitude,
  time: new Date(sample.timestamp),
  elevation: sample.altitudeMeters,
  extensions: {
    speed: sample.speedMetersPerSecond,
    heartRate: sample.heartRate,
    cadence: sample.cadence
  }
}));

const gpx = generateGpx({ name: "Mapped Sensor Track", points });

Node.js file export

Persist the generated XML to a .gpx file.

import { writeFileSync } from "node:fs";

writeFileSync("track.gpx", gpx, "utf8");

Browser download export

Trigger a direct download from XML string output.

const blob = new Blob([gpx], { type: "application/gpx+xml" });
const url = URL.createObjectURL(blob);

const anchor = document.createElement("a");
anchor.href = url;
anchor.download = "track.gpx";
anchor.click();

URL.revokeObjectURL(url);

GitHub · npm