GPX 1.0 Developer's Manual

This Manual is Outdated!

This document applies to GPX 1.0. GPX 1.1 is the current GPX implementation.

Introduction

GPX (the GPS eXchange Format) is a light-weight XML data format for the interchange of GPS data (waypoints, routes, and tracks) between applications and web services on the Internet. This document describes the XML elements defined in GPX in detail and provides examples of their use. The descriptions in this document are designed to help developers interpret the GPX schema, which is the definitive definition of GPX.

Validating your GPX Output

Your application needs to produce valid GPX output before it can be used with other programs and web services that support GPX. As a developer, it is your responsibility to ensure that the GPX data you create validates correctly A GPX file is not a GPX file if it doesn't pass the validator!

XML Namespaces

GPX files should reference at least two namespaces: the XMLSchema namespace, and the GPX namespace. If you include private elements in your GPX files, you need to reference that namespace as well. Here are two examples:

Example using no private elements:
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns="http://www.topografix.com/GPX/1/0"
xsi:schemaLocation="http://www.topografix.com/GPX/1/0 http://www.topografix.com/GPX/1/0/gpx.xsd">

Example from ExpertGPS using TopoGrafix 0.2 private elements:
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns="http://www.topografix.com/GPX/1/0"
xmlns:topografix="http://www.topografix.com/GPX/Private/TopoGrafix/0/2"
xsi:schemaLocation="http://www.topografix.com/GPX/1/0 http://www.topografix.com/GPX/1/0/gpx.xsd http://www.topografix.com/GPX/Private/TopoGrafix/0/2 http://www.topografix.com/GPX/Private/TopoGrafix/0/2/topografix.xsd">

All GPX files contain one <gpx> element as the outermost element. <gpx> contains the following:

• Required file information
• Optional file information
• <wpt> Optional Waypoints
• <rte> Optional Routes
• <trk> Optional Tracks
• Optional Private Elements

All GPX files must contain the following attributes:

• <version> GPX schema version used in file
• <creator> Program used to create file

• <name> Descriptive name of the GPX file
• <desc> Description of the GPX file
• <author> Name of the file's creator
• <email> Email address of the file's creator
• <url> URL associated with the file
• <urlname> Text to display on the <url> hyperlink
• <time> Creation date/time of the GPX file
• <keywords> Keywords for categorizing the GPX file in a database or search engine
• <bounds> Bounding rectangle for the data in the file.

Required Information:
• <lat> Latitude of the waypoint.
• <lon> Longitude of the waypoint.

Optional Position Information:
• <ele> Elevation of the waypoint.
• <time> Creation date/time of the waypoint
• <magvar> Magnetic variation of the waypoint
• <geoidheight> Geoid height of the waypoint

Optional Description Information:
• <name> GPS waypoint name of the waypoint
• <cmt> GPS comment of the waypoint
• <desc> Descriptive description of the waypoint
• <src> Source of the waypoint data
• <url> URL associated with the waypoint
• <urlname> Text to display on the <url> hyperlink
• <sym> Waypoint symbol
• <type> Type (category) of waypoint

Optional Accuracy Information:
• <fix> Type of GPS fix
• <sat> Number of satellites
• <hdop> HDOP
• <vdop> VDOP
• <pdop> PDOP
• <ageofdgpsdata> Time since last DGPS fix
• <dgpsid> DGPS station ID

Optional Private Information:
• Private Elements

Optional Information
• <name> GPS route name
• <cmt> GPS route comment
• <desc> Description of the route
• <src> Source of the route data
• <url> URL associated with the route
• <urlname> Text to display on the <url> hyperlink
• <number> GPS route number
• Private Elements
• List of routepoints

Required Information:
• <lat> Latitude of the routepoint.
• <lon> Longitude of the routepoint.

Optional Position Information:
• <ele> Elevation of the routepoint.
• <time> Creation date/time of the routepoint
• <magvar> Magnetic variation of the routepoint
• <geoidheight> Geoid height of the routepoint

Optional Description Information:
• <name> GPS waypoint name of the routepoint
• <cmt> GPS comment of the routepoint
• <desc> Descriptive description of the routepoint
• <src> Source of the routepoint data
• <url> URL associated with the routepoint
• <urlname> Text to display on the <url> hyperlink
• <sym> routepoint symbol
• <type> Type (category) of routepoint

Optional Accuracy Information:
• <fix> Type of GPS fix
• <sat> Number of satellites
• <hdop> HDOP
• <vdop> VDOP
• <pdop> PDOP
• <ageofdgpsdata> Time since last DGPS fix
• <dgpsid> DGPS station ID

Optional Private Information:
• Private Elements

Optional Information
• <name> GPS track name
• <cmt> GPS track comment
• <desc> Description of the track
• <src> Source of the track data
• <url> URL associated with the track
• <urlname> Text to display on the <url> hyperlink
• <number> GPS track number
• Private Elements
• List of Track Segments

A Track Segment holds a list of Track Points which are logically connected in order. To represent a single GPS track where GPS reception was lost, or the GPS receiver was turned off, start a new Track Segment for each continuous span of track data.

Optional Information:
• List of Track Points

Optional Required Information:
• <lat> Latitude of the trackpoint.
• <lon> Longitude of the trackpoint.

Optional Position Information:
• <ele> Elevation of the trackpoint.
• <time> Creation date/time of the trackpoint
• <magvar> Magnetic variation of the trackpoint
• <geoidheight> Geoid height of the trackpoint

Optional Description Information:
• <name> GPS waypoint name of the trackpoint
• <cmt> GPS comment of the trackpoint
• <desc> Descriptive description of the trackpoint
• <src> Source of the trackpoint data
• <url> URL associated with the trackpoint
• <urlname> Text to display on the <url> hyperlink
• <sym> trackpoint symbol
• <type> Type (category) of trackpoint

Optional Accuracy Information:
• <fix> Type of GPS fix
• <sat> Number of satellites
• <hdop> HDOP
• <vdop> VDOP
• <pdop> PDOP
• <ageofdgpsdata> Time since last DGPS fix
• <dgpsid> DGPS station ID

Optional Private Information:
• Private Elements

Required Attributes

Required in: <gpx>

<gpx version="0.6" ... >

All GPX files must include the version of the GPX schema which the file references.

Required in: <gpx>

<gpx ... creator="EasyGPS 1.1 - www.easygps.com" ... >

All GPX files must include the name of the application or web service which created the file. This is to assist developers in tracking down the source of a mal-formed GPX document, and to provide a hint to users as to how they can open the file.

Required in: <wpt> <rtept> <trkpt>

Units: Decimal degrees, WGS84

<wpt lat="42.323" ... >

The latitude of the point.

Required in: <wpt> <rtept> <trkpt>

Units: Decimal degrees, WGS84

<wpt ... lon="-71.20453" ... >

The longitude of the point.

Optional Elements

Optional in: <gpx> <wpt> <rte> <rtept> <trk> <trkpt>

<gpx>: <name>Five Hikes in the White Mountains</name>

<wpt>: <name>MTWASHINGT</name>

<rte>: <name>CRAW PATH</name>

<rtept>: <name>DAVISTRL</name>

In <gpx>: the name of the file.

In all other elements: the GPS name of the element. This field will be transferred to and from the GPS. GPX does not place restrictions on the length of this field or the characters contained in it. It is up to the receiving application to validate the field before sending it to the GPS.

Optional in: <gpx> <wpt> <rte> <rtept> <trk> <trkpt>

<gpx>: <desc>Five Hikes in the White Mountains</desc>

<wpt>: <desc>Mount Washington</desc>

<rte>: <desc>Crawford Path Hike</desc>

<rtept>: <desc>Junction with Davis Trail</desc>

A text description of the element. Holds additional information about the element intended for the user, not the GPS.

Optional in: <gpx>

<author>Dan Foster</author>

The author of the GPX file. The GPX file's owner/creator.

Optional in: <gpx>

<email>danfoster95@yahoo.com</email>

Email address associated with the GPX file. Usually contact email address of the GPX file's author.

Optional in: <gpx> <wpt> <rte> <rtept> <trk> <trkpt>

<url>www.mountwashington.org/</url>

URL associated with the element. Webpage or additional info connected to element.

Optional in: <gpx> <wpt> <rte> <rtept> <trk> <trkpt>

<urlname>Visit my New Hampshire hiking website!</urlname>

Hyperlink text associated with the URL.

Optional in: <gpx> <wpt> <rte> <rtept> <trk> <trkpt>

<time>2002-02-10T21:01:29.250Z</time>

Creation/modification timestamp for element. Date and time in are in Univeral Coordinated Time (UTC), not local time! Conforms to ISO 8601 specification for date/time representation. Fractional seconds are allowed for millisecond timing in tracklogs.

Optional in: <gpx>

<keywords>Hiking, NH, Presidential Range</keywords>

Keywords for indexing the GPX file with search engines. Comma separated.

Optional in: <gpx>

<bounds minLat="42.1" minlon="-71.9" maxLat="42.4" maxlon="-71.1" />

Bounding rectangle of all data in GPX file. Allows indexing by geographic extent.

Position Information

Optional in: <wpt> <rtept> <trkpt>

Units: meters

<ele>1206.2</ele>

Elevation in meters of the point.

Optional in: <wpt> <rtept> <trkpt>

Units: degrees, true

<course>45.2</course>

Instantaneous course at the point.

Optional in: <wpt> <rtept> <trkpt>

Units: meters per second

<speed>4.23</speed>

Instantaneous speed at the point.

Optional in: <wpt> <rtept> <trkpt>

Units: degrees

<magvar>-16.2</magvar>

Magnetic variation at the point.

Optional in: <wpt> <rtept> <trkpt>

Units: meters

<geoidheight>-16.2</geoidheight>

Height, in meters, of geoid (mean sea level) above WGS-84 earth ellipsoid. (NMEA GGA message)

Optional in: <wpt> <rte> <rtept> <trk> <trkpt>

<cmt>MT WASHINGTON</cmt>

GPS waypoint comment. Sent to GPS as comment.

Optional in: <wpt> <rte> <rtept> <trk> <trkpt>

<src>Garmin eTrex Venture</src>

<src>USGS Mount Washington 7.5 Quad</src>

Source of data. Included to give user some idea of reliability and accuracy of data.

Optional in: <wpt> <rtept> <trkpt>

<sym>Scenic Area</sym>

Text of GPS symbol name. For interchange with other programs, use the exact spelling of the symbol on the GPS, if known.

Optional in: <wpt> <rtept> <trkpt>

<type>Hiking trail</type>

Type (classification) of element.

Optional in: <wpt> <rtept> <trkpt>

<fix>2d</fix>

Type of GPX fix.

Must be one of:
• none No fix
• 2d position only
• 3d position and elevation
• dgps DGPS
• pps Military signal used

To represent "fix type unknown", leave out fix entirely.

Optional in: <wpt> <rtept> <trkpt>

<sat>8</sat>

Number of satellites used to calculate the GPS fix. (not number of satellites in view).

Optional in: <wpt> <rtept> <trkpt>

<hdop>1.4</hdop>

Horizontal dilution of precision.

Optional in: <wpt> <rtept> <trkpt>

<vdop>3.2</vdop>

Vertical dilution of precision.

Optional in: <wpt> <rtept> <trkpt>

<pdop>1.4</pdop>

Position dilution of precision.

Optional in: <wpt> <rtept> <trkpt>

<ageofdgpsdata>21</ageofdgpsdata>

Number of seconds since last DGPS update.

Optional in: <wpt> <rtept> <trkpt>

<dgpsid>142</dgpsid>

ID of DGPS station used in differential correction.

Optional in: <rte> <trk>

<number>2</number>

GPS slot number for element.

GPX Home