Skip to content
Saimul Islam

gpx-privacy: edit a GPX file to trim your start and end before you share it

Make GPX tracks safe to share: trim the start and end, simplify the track, compute distance and climb, and write a minimal clean GPX file.

Install
npm install gpx-privacy

Overview

A recorded ride or run starts and ends at your front door. gpx-privacy edits a GPX file to fix that: it hides the first and last 500 m of the track (wherever along the track they recur), simplifies what is left, works out the distance, climb and duration, and writes a minimal GPX file with nothing but positions, heights and times.

It is a library and a command-line tool with one runtime dependency. @tmcw/togeojson and gpxparser read GPX into GeoJSON or plain objects and leave the privacy step to you. gpx-privacy starts where they stop: it trims the ends, thins the line, and returns a clean file you can publish.

Examples

Trim a ride and write the public copy
npx gpx-privacy ride.gpx -o ride-public.gpx
Sample output
gpx-privacy: ride.gpx -> ride-public.gpx
  Trimmed   500 m from the start and the end
  Points    2,001 -> 500
  Distance  43.98 km
  Climb     343 m
  Descent   344 m
  Duration  1:40:00
Trim, thin the line and drop timestamps
gpx-privacy ride.gpx -o ride-public.gpx --trim 300 --max-points 300 --drop-times
Use it from code
import { makeShareable } from 'gpx-privacy';

const { gpx, stats, shared, points } = makeShareable(xml, { trim: 500, maxPoints: 500 });
// gpx: the clean document, stats.distance: metres of the whole ride, points: { input: 2001, output: 500 }

Features

01Trim the start and end
Every point within 500 m (or the radius you choose) of the first or last point is removed, anywhere on the track, so a long wait at home or a pass by the door halfway through never shows it.
02Simplify the track
Douglas-Peucker ranks points by how much of the line shape they hold and keeps the best 500 by default, in order, plus the ends of every segment.
03Distance, climb and duration
Stats for the whole track and for the file you share. Climb uses a 5 m hysteresis so GPS noise adds nothing, and a real hill does.
04A rebuilt, minimal file
The GPX is written from the kept points, so waypoints, author, device and extension data from the original cannot carry over. Timestamps can be dropped with --drop-times.
05Safe parsing
The XML parser runs with entity processing off, so a DOCTYPE cannot expand entities. Files over 10 MiB are refused before parsing.
06Library and CLI
The library uses no Node APIs, so it also runs in browsers; only the CLI reads and writes files. The CLI never overwrites its input.

CLI usage

Usage
gpx-privacy <in.gpx> [-o out.gpx] [--trim 500] [--max-points N] [--drop-times] [--stats] [--json]
-o, --output <file>
Write the GPX to this file instead of stdout.
--trim <metres>
Hide this far around the start and the end. 0 hides nothing. Default: 500.
--max-points <n>
Keep at most this many points. Default: 500.
--drop-times
Leave the timestamps out of the GPX.
--stats
Print distance, climb, descent and duration to stderr.
--json
Print the stats as JSON to stderr (implies --stats).

Limits

  • A trim hides where a ride starts and ends. It does not hide a workplace or a friend's house you pass, and a track that leaves 500 m from your door still shows the direction and the neighbourhood. It is not anonymisation.
  • Heights and times are kept unless you ask otherwise. Times show when you leave and arrive; use --drop-times to leave them out. Heights are always kept.
  • The stats of the whole track include the part that was hidden, so they reveal the true length of the ride. Use the shared figures for the file you publish.
  • 500 points is coarse for a long ride. Raise --max-points when you want more detail.
  • Distance is flat 2D haversine, within roughly 0.5% of an ellipsoidal figure, so climb and descent will not match a given app or watch.
  • Tracks and routes only: waypoints are ignored. GPX in, GPX out; TCX, FIT and KML are not read.

Frequently asked questions

How do I trim a GPX file?

Run npx gpx-privacy ride.gpx -o ride-public.gpx. It removes every point within 500 m of the start and the end, simplifies the rest to at most 500 points and writes a new GPX file. Change the radius with --trim.

Can I hide my home address on Strava or other sites?

It does the same job as a privacy zone, on the file itself: trim the track before you upload it. A trim hides where the ride starts and ends, not the neighbourhood, so choose a larger --trim if that matters. It is not anonymisation.

Is there a web editor for GPX files?

No. gpx-privacy is a command-line tool and a library. The library uses no Node APIs, so you can run it in a browser page of your own.

Can it convert GPX to GeoJSON?

No: GPX in, GPX out. parseGpx() returns the points and segments, so you can convert them yourself, or use @tmcw/togeojson, which reads GPX into GeoJSON.

  • Desktop apps

    active-window-sessions

    Turn active-win style polling into clean time segments per app and per website: merges short gaps, drops blips, respects idle time, ignores system UI and totals each app.

  • Localization

    translation-facts

    Translation quality assurance for the facts in a string: check that numbers, prices, percentages, URLs, emails and {placeholders} survive translation.

See all 9 open-source packages

Author

Built by Saimul Islam

Saimul Islam is a Forward Deployed Engineer and Solutions Architect. Several of these packages run in production on DeveloperLook, the Bundlewise CRM and Sitessa.