GPX file format

Schema overview: GPX 1.0 vs 1.1

Every GPX document is a well-formed XML file with a single root <gpx> element that declares its version and a creator string. Two schema versions are in circulation:

• GPX 1.0 (2002) — carried optional per-point fields like <speed> and <course> directly in the schema. XSD: topografix.com/GPX/1/0/gpx.xsd.
• GPX 1.1 (2004, current) — dropped those fixed fields in favour of a generic <extensions> element, so vendors extend the format without altering the core schema. XSD: topografix.com/GPX/1/1/gpx.xsd.

A minimal, valid GPX 1.1 file:

<?xml version="1.0" encoding="UTF-8"?>
<gpx version="1.1" creator="ExampleApp"
     xmlns="http://www.topografix.com/GPX/1/1"
     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
     xsi:schemaLocation="http://www.topografix.com/GPX/1/1
       http://www.topografix.com/GPX/1/1/gpx.xsd">
  <trk><name>Example</name><trkseg>
    <trkpt lat="47.365" lon="8.549"><ele>412</ele></trkpt>
  </trkseg></trk>
</gpx>

Beware of files that declare version="2.0" or similar — there is no official GPX 2.x. Those are non-standard and should be rejected or treated as suspect.

Required vs optional elements

Trackpoint anatomy

A trackpoint is the atom of a track. Its position is in attributes; everything else is optional child elements:

<trkpt lat="47.36540" lon="8.54890">  <!-- required: WGS 84 decimal degrees -->
  <ele>412.7</ele>                     <!-- optional: metres above sea level -->
  <time>2026-05-18T07:14:32Z</time>    <!-- optional: ISO 8601, UTC (Z) -->
  <extensions>...</extensions>          <!-- optional: HR, cadence, etc. -->
</trkpt>

Note that GPX does not store speed on a 1.1 trackpoint — speed is derived by dividing the distance between consecutive points by the time between their timestamps. That is exactly how the GPX viewer computes per-point speed for its map heat-zones, so a file with no <time> values can show distance and elevation but not speed.

Extensions (Garmin TrackPointExtension)

GPX 1.1's <extensions> element is how sensor data rides along. The most widely used is Garmin's TrackPointExtension, which adds heart rate, cadence, temperature, and more. Declare its namespace on the root element, then nest it inside a point:

<trkpt lat="47.365" lon="8.549">
  <extensions>
    <gpxtpx:TrackPointExtension>
      <gpxtpx:hr>148</gpxtpx:hr>      <!-- bpm -->
      <gpxtpx:cad>86</gpxtpx:cad>     <!-- rpm -->
      <gpxtpx:atemp>19</gpxtpx:atemp> <!-- °C -->
    </gpxtpx:TrackPointExtension>
  </extensions>
</trkpt>

The schema lives at Garmin's TrackPointExtension v2 XSD. A parser that does not understand an extension should skip it silently — extensions are, by design, ignorable.

Multi-track and multi-segment files

A GPX file can contain more than one <trk>, and each track more than one <trkseg>. Segments usually mark a pause: when a recording is stopped and resumed, most devices start a new <trkseg> rather than drawing a straight line across the gap. When you compute distance, sum within each segment and do not connect the last point of one segment to the first of the next — otherwise a coffee stop adds a phantom kilometre.

Common parsing pitfalls

• Missing elevation or time — the two most common absences. Guard every read; do not divide by a time delta of zero.
• No track at all — some files carry only <rte> (planned route) or only <wpt> (waypoints). Fall back to route points, then waypoints, before declaring a file empty.
• Namespace-qualified extensions — gpxtpx:hr will not be found by a reader that ignores namespaces or hard-codes the wrong prefix.
• Fake extensions like .gpx.txt — a download that arrives with a doubled or wrong extension is still valid XML; sniff the content, not just the filename.
• Bogus "GPX 2.x" — reject or flag versions that are not 1.0 or 1.1.
• Coordinate precision and order — lat/lon are attributes in that order is not guaranteed; parse by name, and keep full decimal precision to avoid drift.

Test files

To exercise these edge cases, use our free sample GPX corpus — it includes a waypoints-only file, a route-points-only file, a multi-segment track, and a 25,000-point large file, all released as CC0. They double as a parser test matrix. If you just need to eyeball a file rather than parse it, see how to open a GPX file on Mac or Windows.

Frequently asked questions

What is the difference between GPX 1.0 and GPX 1.1?

GPX 1.0 (2002) put optional data such as speed and course directly on each point. GPX 1.1 (2004) removed those fixed fields and introduced a formal <extensions> mechanism so vendors can add their own data without breaking the schema. GPX 1.1 is the current version; both use the same core track/route/waypoint structure.

Are latitude, longitude and elevation required in a trackpoint?

Latitude and longitude are required attributes on every trkpt, rtept and wpt. Elevation (<ele>) and time (<time>) are optional child elements — many valid GPX files omit one or both, so a robust parser must treat them as absent rather than assume they exist.

How do I add heart rate or cadence to a GPX file?

Use the Garmin TrackPointExtension schema inside a trackpoint's <extensions> element: <gpxtpx:TrackPointExtension> can hold <gpxtpx:hr>, <gpxtpx:cad>, <gpxtpx:atemp> and more. Declare the gpxtpx namespace on the root <gpx> element so the extension validates.