GPX - GPS Exchange Format

(Starting with GDAL 1.5.0)

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.

OGR has support for GPX reading (if GDAL is build with expat library support) and writing.

Version supported are GPX 1.0 and 1.1 for reading, GPX 1.1 for writing.

The OGR driver supports reading and writing of all the GPX feature types :

It also supports reading of route points and track points in standalone layers (route_points and track_points), so that their own attributes can be used by OGR.

In addition to its GPX attributes, each route point of a route has a route_fid (foreign key to the FID of its belonging route) and a route_point_id which is its sequence number in the route.
The same applies for track points with track_fid, track_seg_id and track_seg_point_id. All coordinates are relative to the WGS84 datum (EPSG:4326).

If the environment variable GPX_ELE_AS_25D is set to YES, the elevation element will be used to set the Z coordinates of waypoints, route points and track points.

The OGR/GPX reads and writes the GPX attributes for the waypoints, routes and tracks.

By default, up to 2 <link> elements can be taken into account by feature. This default number can be changed with the GPX_N_MAX_LINKS environment variable.

Encoding issues

Expat library supports reading the following built-in encodings : OGR 1.8.0 adds supports for Windows-1252 encoding (for previous versions, altering the encoding mentioned in the XML header to ISO-8859-1 might work in some cases).

The content returned by OGR will be encoded in UTF-8, after the conversion from the encoding mentioned in the file header is.

If your GPX file is not encoded in one of the previous encodings, it will not be parsed by the GPX driver. You may convert it into one of the supported encoding with the iconv utility for example and change accordingly the encoding parameter value in the XML header.

When writing a GPX file, the driver expects UTF-8 content to be passed in.

Extensions element reading

If the <extensions> element is detected in a GPX file, OGR will expose the content of its sub elements as fields. Complex content of sub elements will be exposed as an XML blob.

The following sequence GPX content :

        <navaid:name>TOTAL RF</navaid:name>
        <navaid:frequency type="CTAF" frequency="122.900" name="CTAF"/>
        <navaid:runway designation="H1" length="80" width="80" surface="ASPH-G">
will be interpreted in the OGR SF model as :
  navaid_name (String) = TOTAL RF
  navaid_address (String) = BENSALEM
  navaid_state (String) = PA
  navaid_country (String) = US
  navaid_frequencies (String) = <navaid:frequency type="CTAF" frequency="122.900" name="CTAF" ></navaid:frequency>
  navaid_runways (String) = <navaid:runway designation="H1" length="80" width="80" surface="ASPH-G" ></navaid:runway>
  navaid_magvar (Integer) = 12

Note : the GPX driver will output content of the extensions element only if it is found in the first records of the GPX file. If extensions appear later, you can force an explicit parsing of the whole file with the GPX_USE_EXTENSIONS environment variable.

Creation Issues

On export all layers are written to a single GPX file. Update of existing files is not currently supported.

If the output file already exits, the writing will not occur. You have to delete the existing file first.

Supported geometries :

For route points and tracks points, if there is a Z coordinate, it is used to fill the elevation element of the corresponding points.

Starting with GDAL/OGR 1.8.0, if a layer is named "track_points" with wkbPoint/wkbPoint25D geometries, the tracks in the GPX file will be built from the sequence of features in that layer. This is the way of setting GPX attributes for each track point, in addition to the raw coordinates. Points belonging to the same track are identified thanks to the same value of the 'track_fid' field (and it will be broken into track segments according to the value of the 'track_seg_id' field). They must be written in sequence so that track objects are properly reconstructed. The 'track_name' field can be set on the first track point to fill the <name> element of the track. Similarly, if a layer is named "route_points" with wkbPoint/wkbPoint25D geometries, the routes in the GPX file will be built from the sequence of points with the same value of the 'route_fid' field. The 'route_name' field can be set on the first track point to fill the <name> element of the route.

The GPX writer supports the following layer creation options:

The GPX writer supports the following dataset creation options:

Waypoints, routes and tracks must be written into that order to be valid against the XML Schema.

When translating from a source dataset, it may be necessary to rename the field names from the source dataset to the expected GPX attribute names, such as <name>, <desc>, etc... This can be done with a OGR VRT dataset, or by using the "-sql" option of the ogr2ogr utility.

Issues when translating to Shapefile

VSI Virtual File System API support

(Some features below might require OGR >= 1.9.0)

The driver supports reading and writing to files managed by VSI Virtual File System API, which include "regular" files, as well as files in the /vsizip/ (read-write) , /vsigzip/ (read-write) , /vsicurl/ (read-only) domains.

Writing to /dev/stdout or /vsistdout/ is also supported.


  • The ogrinfo utility can be used to dump the content of a GPX datafile :
    ogrinfo -ro -al input.gpx

  • The ogr2ogr utility can be used to do GPX to GPX translation :
    ogr2ogr -f GPX output.gpx input.gpx waypoints routes tracks

    Note : in the case of GPX to GPX translation, you need to specify the layer names, in order to discard the route_points and track_points layers.

  • Use of the <extensions> tag for output :
    ogr2ogr -f GPX  -dsco GPX_USE_EXTENSIONS=YES output.gpx input
    which will give an output like the following one :
        <?xml version="1.0"?>
        <gpx version="1.1" creator="GDAL 1.5dev"
        <wpt lat="1" lon="2">
        <wpt lat="3" lon="4">
  • Use of -sql option to remap field names to the ones allowed by the GPX schema (starting with GDAL 1.6.0):
    ogr2ogr -f GPX output.gpx input.shp -sql "SELECT field1 AS name, field2 AS desc FROM input"
  • FAQ

  • How to solve "ERROR 6: Cannot create GPX layer XXXXXX with unknown geometry type" ?

    This error happens when the layer to create does not expose a precise geometry type, but just a generic wkbUnknown type. This is for example the case when using ogr2ogr with a SQL request to a PostgreSQL datasource. You must then explicitly specify -nlt POINT (or LINESTRING or MULTILINESTRING).

  • See Also