API Reference#

`gpx.gpx` Module#

This module provides a GPX object to contain GPX files, consisting of waypoints, routes and tracks.

class gpx.gpx.GPX(element=None)#

Bases: Element

A GPX class for the GPX data format.

GPX documents contain a metadata header, followed by waypoints, routes, and tracks. You can add your own elements to the extensions section of the GPX document.

Parameters:: element (etree._Element | None) – The GPX XML element. Defaults to None.

creator: str#: The name or URL of the software that created your GPX document. Defaults to “PyGPX”.

metadata: Metadata | None#: Metadata about the file.

waypoints: list[gpx.waypoint.Waypoint]#: A list of waypoints.

routes: list[gpx.route.Route]#: A list of routes.

tracks: list[gpx.track.Track]#: A list of tracks.

property name: str | None#

The name of the GPX file.

Alias of gpx.metadata.Metadata.name.

property desc: str | None#

A description of the contents of the GPX file.

Alias of gpx.metadata.Metadata.desc.

property author: Person | None#

The person or organization who created the GPX file.

Alias of gpx.metadata.Metadata.author.

property copyright: Copyright | None#

Alias of gpx.metadata.Metadata.copyright.

property links: list[gpx.link.Link] | None#

URLs associated with the location described in the file.

Alias of gpx.metadata.Metadata.links.

property time: datetime | None#

The creation date of the file.

Alias of gpx.metadata.Metadata.time.

property keywords: str | None#

Keywords associated with the file. Search engines or databases can use this information to classify the data.

Alias of gpx.metadata.Metadata.keywords.

property bounds: Bounds | None#

Minimum and maximum coordinates which describe the extent of the coordinates in the file.

Alias of gpx.metadata.Metadata.bounds.

classmethod from_string(gpx_str, validate=False)#

Create an GPX instance from a string.

>>> from gpx import GPX
>>> gpx = GPX.from_str("""<?xml version="1.0" encoding="UTF-8" ?>
... <gpx xmlns="http://www.topografix.com/GPX/1/1" creator="PyGPX" version="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">
...     [...]
... </gpx>""")
>>> print(gpx.bounds)

Parameters:

gpx_str (str) – The string containing the GPX data.
validate (bool) – Whether to validate the GPX data.

Returns:

The GPX instance.

Return type:

GPX

classmethod from_file(gpx_file, validate=False)#

Create an GPX instance from a file.

>>> from gpx import GPX
>>> gpx = GPX.from_file("path/to/file.gpx")
>>> print(gpx.bounds)

Parameters:

gpx_file (str | Path) – The file containing the GPX data.
validate (bool) – Whether to validate the GPX data.

Returns:

The GPX instance.

Return type:

GPX

to_string()#

Serialize the GPX instance to a string.

Returns:: The GPX data as a string.
Return type:: str

to_file(gpx_file)#

Serialize the GPX instance to a file.

Parameters:: gpx_file (str | Path) – The file to write the GPX data to.

`gpx.metadata` Module#

This module provides a Metadata object to contain GPX metadata, containing information about the GPX file, author, and copyright restrictions.

class gpx.metadata.Metadata(element=None)#

Bases: Element

A metadata class for the GPX data format.

Information about the GPX file, author, and copyright restrictions goes in the metadata section. Providing rich, meaningful information about your GPX files allows others to search for and use your GPS data.

Parameters:: element (etree._Element | None) – The metadata XML element. Defaults to None.

name: str | None#: The name of the GPX file.

desc: str | None#: A description of the contents of the GPX file.

author: Person | None#: The person or organization who created the GPX file.

copyright: Copyright | None#: Copyright and license information governing use of the file.

links: list[gpx.link.Link]#: URLs associated with the location described in the file.

time: datetime | None#: The creation date of the file.

keywords: str | None#: Keywords associated with the file. Search engines or databases can use this information to classify the data.

bounds: Bounds | None#: Minimum and maximum coordinates which describe the extent of the coordinates in the file.

`gpx.waypoint` Module#

This module provides a Waypoint object to contain GPX waypoints.

class gpx.waypoint.Waypoint(element=None)#

Bases: Element

A waypoint class for the GPX data format.

A waypoint represents a waypoint, point of interest, or named feature on a map.

Parameters:: element (etree._Element | None) – The waypoint XML element. Defaults to None.

lat: Latitude#: The latitude of the point. Decimal degrees, WGS84 datum.

lon: Longitude#: The longitude of the point. Decimal degrees, WGS84 datum.

ele: Decimal | None#: Elevation (in meters) of the point.

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

magvar: Degrees | None#: Magnetic variation (in degrees) at the point

geoidheight: Decimal | None#: Height (in meters) of geoid (mean sea level) above WGS84 earth ellipsoid. As defined in NMEA GGA message.

name: str | None#: The GPS name of the waypoint. 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.

cmt: str | None#: GPS waypoint comment. Sent to GPS as comment.

desc: str | None#: A text description of the element. Holds additional information about the element intended for the user, not the GPS.

src: str | None#: Source of data. Included to give user some idea of reliability and accuracy of data. “Garmin eTrex”, “USGS quad Boston North”, e.g.

links: list[gpx.link.Link]#: Link to additional information about the waypoint.

sym: str | None#: Text of GPS symbol name. For interchange with other programs, use the exact spelling of the symbol as displayed on the GPS. If the GPS abbreviates words, spell them out.

type: str | None#: Type (classification) of the waypoint.

fix: Fix | None#: Type of GPX fix.

sat: int | None#: Number of satellites used to calculate the GPX fix.

hdop: Decimal | None#: Horizontal dilution of precision.

vdop: Decimal | None#: Vertical dilution of precision.

pdop: Decimal | None#: Position dilution of precision.

ageofdgpsdata: Decimal | None#: Number of seconds since last DGPS update.

dgpsid: DGPSStation | None#: ID of DGPS station used in differential correction.

distance_to(other, radius=6378137)#

Returns the distance to the other waypoint (in metres) using a simple spherical earth model (haversine formula).

Parameters:

other (Waypoint) – The other waypoint.
radius (int) – The radius of the earth (defaults to 6,378,137 metres).

Returns:

The distance to the other waypoint (in metres).

Return type:

float

Adapted from: https://github.com/chrisveness/geodesy/blob/33d1bf53c069cd7dd83c6bf8531f5f3e0955c16e/latlon-spherical.js#L187-L205

duration_to(other)#

Returns the duration to the other waypoint.

Parameters:: other (Waypoint) – The other waypoint.
Returns:: The duration to the other waypoint.
Return type:: timedelta

`gpx.route` Module#

This module provides a Route object to contain GPX routes - ordered lists of waypoints representing a series of turn points leading to a destination.

class gpx.route.Route(element=None)#

Bases: Element, PointsMutableSequenceMixin

A route class for the GPX data format.

A route represents an ordered list of waypoints representing a series of turn points leading to a destination.

Parameters:: element (etree._Element | None) – The route XML element. Defaults to None.

name: str | None#: GPS name of route.

cmt: str | None#: GPS comment for route.

desc: str | None#: Text description of route for user. Not sent to GPS.

src: str | None#: Source of data. Included to give user some idea of reliability and accuracy of data.

links: list[gpx.link.Link]#: Links to external information about the route.

number: int | None#: GPS route number.

type: str | None#: Type (classification) of route.

rtepts: list[gpx.waypoint.Waypoint]#: A list of route points.

points: list[gpx.waypoint.Waypoint]#: Alias of rtepts.

property bounds: tuple[gpx.types.Latitude, gpx.types.Longitude, gpx.types.Latitude, gpx.types.Longitude]#: The bounds of the route.

`gpx.track` Module#

This module provides a Track object to contain GPX routes - an ordered list of points describing a path.

class gpx.track.Track(element=None)#

Bases: Element

A track class for the GPX data format.

A track represents an ordered list of points describing a path.

Parameters:: element (etree._Element | None) – The track XML element. Defaults to None.

name: str | None#: GPS name of track.

cmt: str | None#: GPS comment for track.

desc: str | None#: User description of track.

src: str | None#: Source of data. Included to give user some idea of reliability and accuracy of data.

links: list[gpx.link.Link]#: Links to external information about track.

number: int | None#: GPS track number.

type: str | None#: Type (classification) of track.

trksegs: list[gpx.track_segment.TrackSegment]#: 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.

segments#: Alias of trksegs.

property bounds: tuple[gpx.types.Latitude, gpx.types.Longitude, gpx.types.Latitude, gpx.types.Longitude]#: The bounds of the track.

property distance: float#: The distance of the track (in metres).

property duration: timedelta#: The duration of the track (in seconds).

`gpx.track_segment` Module#

This module provides a Track object to contain GPX routes - an ordered list of points describing a path.

class gpx.track_segment.TrackSegment(element=None)#

Bases: Element, PointsMutableSequenceMixin

A track segment class for the GPX data format.

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.

Parameters:: element (etree._Element | None) – The track segment XML element. Defaults to None.

trkpts: list[gpx.waypoint.Waypoint]#: A Track Point holds the coordinates, elevation, timestamp, and metadata for a single point in a track.

points: list[gpx.waypoint.Waypoint]#: Alias of trkpts.

property bounds: tuple[gpx.types.Latitude, gpx.types.Longitude, gpx.types.Latitude, gpx.types.Longitude]#: The bounds of the track segment.

property distance: float#: The distance of the track segment (in metres).

property duration: timedelta#: The total duration of the track segment.

`gpx.copyright` Module#

This module provides a Copyright object to contain GPX copyright, containing information about the copyright holder and any license governing use of the GPX data.

class gpx.copyright.Copyright(element=None)#

Bases: Element

A copyright class for the GPX data format.

Information about the copyright holder and any license governing use of this file. By linking to an appropriate license, you may place your data into the public domain or grant additional usage rights.

Parameters:: element (etree._Element | None) – The copyright XML element. Defaults to None.

author: str#: Copyright holder (e.g. TopoSoft, Inc.).

year: int | None#: Year of copyright.

license: str | None#: Link to external file containing license text.

`gpx.link` Module#

This module provides a Link object to contain GPX links to external resources (Web page, digital photo, video clip, etc) with additional information.

class gpx.link.Link(element=None)#

Bases: Element

A link class for the GPX data format.

A link to an external resource (Web page, digital photo, video clip, etc) with additional information.

Parameters:: element (etree._Element | None) – The link XML element. Defaults to None.

href: str#: URL of hyperlink.

text: str | None#: Text of hyperlink.

type: str | None#: Mime type of content (e.g. image/jpeg)

`gpx.email` Module#

This module provides a Email object to contain an email address.

class gpx.email.Email(element=None)#

Bases: Element

An email class for the GPX data format.

An email address. Broken into two parts (id and domain) to help prevent email harvesting.

Parameters:: element (etree._Element | None) – The email XML element. Defaults to None.

id: str#: id half of email address (e.g. billgates2004)

domain: str#: domain half of email address (e.g. hotmail.com)

`gpx.person` Module#

This module provides a Person object to contain a person or organization.

class gpx.person.Person(element=None)#

Bases: Element, AttributesMutableMappingMixin

A person class for the GPX data format.

A person or organization.

Parameters:: element (etree._Element | None) – The person XML element. Defaults to None.

name: str | None#: Name of person or organization.

email: Email | None#: Email address.

link: Link | None#: Link to Web site or other external information about person.

`gpx.bounds` Module#

This module provides a Bounds object to contain two lat/lon pairs defining the extent of an element.

class gpx.bounds.Bounds(element=None)#

Bases: Element

A bounds class for the GPX data format.

Two lat/lon pairs defining the extent of an element.

Parameters:: element (etree._Element | None) – The bounds XML element. Defaults to None.

minlat: Latitude#: The minimum latitude.

minlon: Longitude#: The minimum longitude.

maxlat: Latitude#: The maximum latitude.

maxlon: Longitude#: The maximum longitude.

as_tuple()#

Return the bounds as a tuple.

`gpx.element` Module#

This module provides an Element object to serve as a base class for other GPX objects.

class gpx.element.Element(element=None)#

Bases: object

Element base class for GPX elements.

Parameters:: element (etree._Element | None) – The XML element. Defaults to None.

_element: _Element | None#: The XML element.

_nsmap: dict[str, str] | None#: The XML namespace mapping from prefix -> URI.

_parse()#

Parses the XML element.

Raises:: ParseError – If the XML element is None.

_build(tag)#

Builds the XML element.

Parameters:: tag (str) – The XML tag.
Returns:: The XML element.
Return type:: _Element

`gpx.mixins` Module#

This module provides a Person object to contain a person or organization.

class gpx.mixins.AttributesMutableMappingMixin#

Bases: MutableMapping

A mixin class to provide a MutableMapping interface to an object’s defined attributes.

class gpx.mixins.PointsSequenceMixin#

Bases: Sequence

A mixin class to provide a Sequence interface to an object’s points.

class gpx.mixins.PointsMutableSequenceMixin#

Bases: PointsSequenceMixin, MutableSequence

A mixin class to provide a MutableSequence interface to an object’s points.

`gpx.types` Module#

This module provides simple type objects to contain various GPX data.

class gpx.types.Latitude(value)#

Bases: Decimal

A latitude class for the GPX data format.

The latitude of the point. Decimal degrees, WGS84 datum.

Parameters:: value (str | int | float | Decimal) – The latitude value.

class gpx.types.Longitude(value)#

Bases: Decimal

A longitude class for the GPX data format.

The longitude of the point. Decimal degrees, WGS84 datum.

Parameters:: value (str | int | float | Decimal) – The longitude value.

class gpx.types.Degrees(value)#

Bases: Decimal

A degrees class for the GPX data format.

Used for bearing, heading, course. Units are decimal degrees, true (not magnetic).

Parameters:: value (str | int | float | Decimal) – The degrees value.

class gpx.types.Fix(value)#

Bases: str

A fix class for the GPX data format.

Type of GPS fix. None means GPS had no fix. To signify “the fix info is unknown”, leave out fix entirely. pps = military signal used.

Parameters:: value (str) – The fix value.

class gpx.types.DGPSStation(value)#

Bases: int

A DGPS station class for the GPX data format.

Represents a differential GPS station.

Parameters:: value (int) – The DGPS station value.

`gpx.utils` Module#

This module contains various utility functions.

gpx.utils.remove_encoding_from_string(s)#

Removes encoding declarations (e.g. encoding=”utf-8”) from the string, if any.

Parameters:: s (str) – The string.
Returns:: The string with any encoding declarations removed.
Return type:: str

`gpx.errors` Module#

This module provices various error types.

exception gpx.errors.InvalidGPXError#

Bases: Exception

GPX is invalid.

exception gpx.errors.ParseError#

Bases: Exception

No element to parse.

API Reference#

gpx.gpx Module#

gpx.metadata Module#

gpx.waypoint Module#

gpx.route Module#

gpx.track Module#

gpx.track_segment Module#

gpx.copyright Module#

gpx.link Module#

gpx.email Module#

gpx.person Module#

gpx.bounds Module#

gpx.element Module#

gpx.mixins Module#

gpx.types Module#

gpx.utils Module#

gpx.errors Module#

`gpx.gpx` Module#

`gpx.metadata` Module#

`gpx.waypoint` Module#

`gpx.route` Module#

`gpx.track` Module#

`gpx.track_segment` Module#

`gpx.copyright` Module#

`gpx.link` Module#

`gpx.email` Module#

`gpx.person` Module#

`gpx.bounds` Module#

`gpx.element` Module#

`gpx.mixins` Module#

`gpx.types` Module#

`gpx.utils` Module#

`gpx.errors` Module#