GISToolsGPX

GPX 1.1 (GPS Exchange Format) read and write support for Swift, built on top of gis-tools. Parses waypoints, routes, and tracks into typed FeatureCollection objects — and writes them back as valid GPX XML.

Features

Reads and writes GPX 1.1 files, with read-only support for GPX 1.0
Waypoints (<wpt>) → Feature<Point>, Routes (<rte>) → Feature<LineString>, Tracks (<trk>) → Feature<MultiLineString>
Typed convenience API on Feature and FeatureCollection — no manual dictionary casting
Full <metadata> block (name, author, copyright, bounds, keywords, time, links)
Garmin TrackPointExtension v2 (gpxtpx): hr, cad, power, speed, course, bearing, temperature, depth
Garmin GpxExtensions v3 (gpxx): Address, Categories, PhoneNumber, DisplayColor, IsAutoNamed, rpt
Structured extension values: Address → GPXAddress, Categories → [String], PhoneNumber → [GPXPhoneNumber]
Automatic type inference for extension values (booleans, integers, floating-point, strings)
Per-point sensor arrays: heart rate, cadence, power, speed, temperature — stored as parallel arrays
gpxPointFeatures(): expand track points into individual Point features with per-point sensor data
Time-window and distance-window slicing of point features
GPX 1.0-specific fields: course/speed on track points, flat url/urlname links
Round-trip fidelity: write → read preserves element types, coordinates, properties, and extensions

Requirements

Swift 6.1 or higher. Compiles on iOS (≥ iOS 15), macOS (≥ macOS 15), tvOS (≥ tvOS 15), watchOS (≥ watchOS 7), Linux, Android and Wasm. No external dependencies beyond the base gis-tools package.

Installation with Swift Package Manager

dependencies: [
    .package(url: "https://github.com/Outdooractive/gis-tools-gpx", from: "1.0.0"),
    .package(url: "https://github.com/Outdooractive/gis-tools", from: "2.0.0"),
],
targets: [
    .target(name: "MyTarget", dependencies: [
        .product(name: "GISToolsGPX", package: "gis-tools-gpx"),
        .product(name: "GISTools", package: "gis-tools"),
    ]),
]

Usage

Reading

import GISTools
import GISToolsGPX

let url = URL(fileURLWithPath: "/path/to/file.gpx")
let fc = try GPXCoder.read(from: url)

// Or via the convenience init:
guard let fc = FeatureCollection(gpx: url) else { return }

Writing

try fc.writeGPX(to: outputURL)

// Or via the coder directly:
try GPXCoder.write(fc, to: outputURL)

Inspecting GPX element types

Each Feature carries a gpxType property identifying its origin:

for feature in fc.features {
    switch feature.gpxType {
    case .waypoint: print("Waypoint: \(feature.gpxName ?? "unnamed")")
    case .route:    print("Route: \(feature.gpxName ?? "unnamed")")
    case .track:    print("Track: \(feature.gpxName ?? "unnamed")")
    case nil:       print("Unknown GPX type")
    }
}

Waypoint properties

let waypoint = fc.features.first!
print(waypoint.gpxName)            // "Reichstag (Berlin)"
print(waypoint.gpxSymbol)          // "City"
print(waypoint.gpxFix)             // .threeDimensional
print(waypoint.gpxSatellites)      // 12
print(waypoint.gpxHDOP)            // 1.5
print(waypoint.gpxTime)            // Optional<Date>

// Coordinate access
let coord = (waypoint.geometry as! Point).coordinate
print(coord.latitude)              // 52.518611
print(coord.longitude)             // 13.376111
print(coord.altitude)              // 35.0

Track and route geometry

let track = fc.features[1]
let multiLine = track.geometry as! MultiLineString
for (i, segment) in multiLine.lineStrings.enumerated() {
    print("Segment \(i): \(segment.coordinates.count) points")
}

let route = fc.features[2]
let lineString = route.geometry as! LineString
print("Route has \(lineString.coordinates.count) waypoints")

Garmin fitness extensions (gpxtpx)

Track-point-level fitness data via typed properties:

var pointFeature = Feature(Point(Coordinate3D(latitude: 52.5, longitude: 13.3)))
pointFeature.gpxHeartRate = 145
pointFeature.gpxCadence = 90
pointFeature.gpxPower = 220        // watts
pointFeature.gpxSpeed = 12.5       // m/s
pointFeature.gpxCourse = 45.0      // degrees true
pointFeature.gpxAirTemperature = 18.5
pointFeature.gpxDepth = 2.0        // meters

// Reading back:
let hr = feature.gpxHeartRate      // Int? (145)
let cad = feature.gpxCadence       // Int? (90)
let speed = feature.gpxSpeed       // Double? (12.5)

Per-point sensor arrays (track Features only)

Track-level fitness data (gpxtpx extensions on <trkpt>) is accumulated into parallel arrays on the track Feature:

let track = fc.features.first { $0.gpxType == .track }!

let hr = track.gpxHeartRates       // [Int?]? — [120, 145, 160, ...]
let cad = track.gpxCadences         // [Int?]? — [80, 90, 95, ...]
let pw = track.gpxPowers            // [Int?]? — [150, 220, ...] (nil = missing)
let spd = track.gpxSpeeds           // [Double?]? — [12.5, ...]
let tmp = track.gpxAirTemperatures  // [Double?]? — [22.5, ...]
let elev = track.gpxElevations      // [Double?]? — [35.0, 38.0, ...]

// Arrays align with coordinates — nil where no data was recorded
for i in 0..<(track.gpxHeartRates?.count ?? 0) {
    if let hr = hr?[i], let cad = cad?[i] {
        print("Point \(i): HR=\(hr), cad=\(cad)")
    }
}

Converting track points to individual Features

Expand the MultiLineString track into individual Point features, each carrying its own sensor data:

let pts = track.gpxPointFeatures()
pts.features.count                  // 3 (one per track point)
pts.features[0].gpxHeartRate        // 120 (via convenience accessor)
pts.features[2].gpxSpeed            // 12.5 (reads from extensions["gpxtpx"])

// Time-window slicing
let morning = track.gpxPointFeatures(from: morningDate, to: noonDate)

// Distance-window slicing (meters along track)
let lastKm = track.gpxPointFeatures(from: totalM - 1000, to: totalM)

// Fractional-window slicing (0.0–1.0)
let middle = track.gpxPointFeatures(fraction: 0.33, to: 0.66)

Reconstructing a track from point features

Convert a FeatureCollection of Point features back into a Feature<MultiLineString> track with per-point sensor arrays rebuilt:

let pts = track.gpxPointFeatures()

// Via FeatureCollection:
let rebuilt = pts.gpxTrackFromPointFeatures()
rebuilt?.gpxHeartRates?[0]   // 120
rebuilt?.gpxSpeeds?[2]        // 12.5

// Via Feature convenience init (also reads extensions["gpxtpx"]):
let track = Feature(gpxTrackFrom: pts)
track?.gpxCadences?[1]        // 90
track?.gpxHeartRate           // nil (track Feature has arrays, not single values)

Non-Point features are silently skipped. Returns nil if no Point features exist. The gpxtpx extension data (hr, cad, power, speed, atemp) is extracted from each point and re-accumulated into parallel arrays, so round-trips preserve sensor data. The track has a single segment (no lap splitting).

Garmin waypoint extensions (gpxx)

Address, categories, and phone numbers as structured types:

let address = waypoint.gpxAddress
print(address?.streetAddresses)    // ["Teststrasse 123", "Floor 4"]
print(address?.city)               // "Berlin"
print(address?.country)            // "Germany"
print(address?.postalCode)         // "10115"

let categories = waypoint.gpxCategories
print(categories)                  // ["Office", "Technology", "Outdoor"]

for phone in waypoint.gpxPhoneNumbers {
    print("\(phone.category ?? "other"): \(phone.value)")
    // Work: +49-30-555-1234
    // Mobile: +49-170-555-5678
}

let isAutoNamed = route.gpxIsAutoNamed  // Bool?
let color = route.gpxDisplayColor       // String? ("Red", "Blue", etc.)

Round-trip: build from scratch

import GISTools
import GISToolsGPX

var fc = FeatureCollection()

// Add metadata
fc.gpxMetadataName = "My GPX File"
fc.gpxMetadataKeywords = "hiking, alps"
fc.gpxMetadataAuthor = GPXPerson(
    name: "Jane Hiker",
    email: "jane@example.com")
fc.gpxMetadataBounds = BoundingBox(
    southWest: Coordinate3D(latitude: 47.0, longitude: 10.0),
    northEast: Coordinate3D(latitude: 48.0, longitude: 11.0))

// Add a waypoint
var wpt = Feature(Point(Coordinate3D(latitude: 47.56, longitude: 10.22)))
wpt.gpxType = .waypoint
wpt.gpxName = "Alpine Lodge"
wpt.gpxSymbol = "Lodging"
wpt.gpxElevation = 1420.0
wpt.gpxAddress = GPXAddress(
    streetAddresses: ["Bergstrasse 1"],
    city: "Oberstdorf",
    country: "Germany",
    postalCode: "87561")
fc.features.append(wpt)

// Add a route
var rte = Feature(LineString(unchecked: [
    Coordinate3D(latitude: 47.56, longitude: 10.22),
    Coordinate3D(latitude: 47.57, longitude: 10.25),
    Coordinate3D(latitude: 47.59, longitude: 10.30),
]))
rte.gpxType = .route
rte.gpxName = "Summit Trail"
rte.gpxTypeName = "Hiking"
fc.features.append(rte)

// Write to file
try fc.writeGPX(to: outputURL)

Setting and writing extensions

var wpt = Feature(Point(Coordinate3D(latitude: 47.56, longitude: 10.22)))
wpt.gpxType = .waypoint
wpt.gpxName = "Checkpoint"

// Fitness data
wpt.gpxHeartRate = 120
wpt.gpxPower = 180

// Structured address
wpt.gpxAddress = GPXAddress(
    streetAddresses: ["Alpenstraße 1"],
    city: "Innsbruck",
    country: "Austria")

// Categories and phone numbers
wpt.gpxCategories = ["Hiking", "Rest Stop"]
wpt.gpxPhoneNumbers = [
    GPXPhoneNumber(value: "+43-512-555", category: "Info"),
]

// Route display properties
wpt.gpxDisplayColor = "Red"
wpt.gpxIsAutoNamed = false

// Write — all extension data round-trips
try FeatureCollection([wpt]).writeGPX(to: outputURL)

GPX 1.0 read support

GPX 1.0 files are parsed with backward-compatible handling:

let fc = try GPXCoder.read(from: gpx10URL)

// GPX 1.0 flat links (url/urlname) converted to GPXLink
let waypoint = fc.features.first!
for link in waypoint.gpxLinks {
    print("\(link.href): \(link.text ?? "")")
    // https://www.bundestag.de: Bundestag website
}

// GPX 1.0 course/speed on track points (not extensions)
// These are stored as gpxCourse10 / gpxSpeed10 on the waypoints
// within track segments, not on the track Feature itself.

OSM traces

OpenStreetMap GPS traces are standard GPX 1.1 files — they read and write like any other GPX:

let trace = try GPXCoder.read(from: osmURL)
let track = trace.features.first { $0.gpxType == .track }!
let multiline = track.geometry as! MultiLineString
print("\(multiline.lineStrings[0].coordinates.count) trace points")

// OSM traces often use cmt/desc for tagging
print(track.gpxDescription)  // e.g. "Walking trace through Berlin Mitte"

Raw extension access

If you need the raw extension dictionary (for namespaces not covered by the typed API):

let ext = feature.properties["extensions"] as? [String: Sendable]
let gpxtpx = ext?["gpxtpx"] as? [String: Sendable]
let gpxx = ext?["gpxx"] as? [String: Sendable]

// Direct key access
let hr = gpxtpx?["hr"] as? Int
let city = (gpxx?["Address"] as? [String: Sendable])?["City"] as? String

Typed API reference

On Feature:

Property	Type	GPX Source
`gpxType`	`GPXElementType?`	`.waypoint`, `.route`, `.track`
`gpxName`	`String?`	`<name>`
`gpxComment`	`String?`	`<cmt>`
`gpxDescription`	`String?`	`<desc>`
`gpxSource`	`String?`	`<src>`
`gpxSymbol`	`String?`	`<sym>`
`gpxTypeName`	`String?`	`<type>`
`gpxFix`	`GPSFixType?`	`<fix>`
`gpxSatellites`	`Int?`	`<sat>`
`gpxHDOP`	`Double?`	`<hdop>`
`gpxVDOP`	`Double?`	`<vdop>`
`gpxPDOP`	`Double?`	`<pdop>`
`gpxTime`	`Date?`	`<time>`
`gpxLinks`	`[GPXLink]`	`<link>`
`gpxCourse10`	`Double?`	`<course>` (GPX 1.0)
`gpxSpeed10`	`Double?`	`<speed>` (GPX 1.0)
`gpxHeartRate`	`Int?`	gpxtpx `hr`
`gpxCadence`	`Int?`	gpxtpx `cad`
`gpxPower`	`Int?`	gpxtpx `power`
`gpxSpeed`	`Double?`	gpxtpx `speed`
`gpxCourse`	`Double?`	gpxtpx `course`
`gpxBearing`	`Double?`	gpxtpx `bearing`
`gpxAirTemperature`	`Double?`	gpxtpx `atemp`
`gpxWaterTemperature`	`Double?`	gpxtpx `wtemp`
`gpxDepth`	`Double?`	gpxtpx `depth`
`gpxHeartRates`	`[Int?]?`	gpxtpx `hr` (per-point array)
`gpxCadences`	`[Int?]?`	gpxtpx `cad` (per-point array)
`gpxPowers`	`[Int?]?`	gpxtpx `power` (per-point array)
`gpxSpeeds`	`[Double?]?`	gpxtpx `speed` (per-point array)
`gpxAirTemperatures`	`[Double?]?`	gpxtpx `atemp` (per-point array)
`gpxElevations`	`[Double?]?`	`<ele>` (per-point array)
`gpxTimes`	`[Date?]?`	`<time>` (per-point array)
`gpxProximity`	`Double?`	gpxx `Proximity`
`gpxDisplayMode`	`String?`	gpxx `DisplayMode`
`gpxAddress`	`GPXAddress?`	gpxx `Address`
`gpxCategories`	`[String]`	gpxx `Categories`
`gpxPhoneNumbers`	`[GPXPhoneNumber]`	gpxx `PhoneNumber`
`gpxIsAutoNamed`	`Bool?`	gpxx `IsAutoNamed`
`gpxDisplayColor`	`String?`	gpxx `DisplayColor`

On FeatureCollection:

Property	Type	GPX Source
`gpxWaypoints`	`[Feature]`	waypoints (filtered by `gpxType`)
`gpxRoutes`	`[Feature]`	routes (filtered by `gpxType`)
`gpxTracks`	`[Feature]`	tracks (filtered by `gpxType`)
`gpxMetadataName`	`String?`	`<metadata><name>`
`gpxMetadataDescription`	`String?`	`<metadata><desc>`
`gpxMetadataKeywords`	`String?`	`<metadata><keywords>`
`gpxMetadataTime`	`Date?`	`<metadata><time>`
`gpxMetadataAuthor`	`GPXPerson?`	`<metadata><author>`
`gpxMetadataCopyright`	`GPXCopyright?`	`<metadata><copyright>`
`gpxMetadataLinks`	`[GPXLink]`	`<metadata><link>`
`gpxMetadataBounds`	`BoundingBox?`	`<metadata><bounds>`

Methods on FeatureCollection:

Method	Returns	Description
`gpxTrackFromPointFeatures()`	`Feature?`	Reconstructs a `Feature<MultiLineString>` from Point features produced by `gpxPointFeatures()`. gpxtpx sensor data is re-accumulated into per-point arrays. Returns `nil` if no Point features exist.

Convenience initializer on Feature:

Initializer	Description
`Feature(gpxTrackFrom:)`	Creates a track Feature from a `FeatureCollection` of Point features. Same as `gpxTrackFromPointFeatures()`.

Public model types:

Type	Fields
`GPXLink`	`href: String`, `text: String?`, `type: String?`
`GPXPerson`	`name: String?`, `email: String?`, `link: GPXLink?`
`GPXCopyright`	`author: String`, `year: Int?`, `license: String?`
`GPXAddress`	`streetAddresses: [String]`, `city: String?`, `state: String?`, `country: String?`, `postalCode: String?`
`GPXPhoneNumber`	`value: String`, `category: String?`

Supported extension namespaces

Prefix	Namespace URI	Elements
`gpxtpx`	`http://www.garmin.com/xmlschemas/TrackPointExtension/v2`	hr, cad, power, speed, course, bearing, atemp, wtemp, depth
`gpxx`	`http://www.garmin.com/xmlschemas/GpxExtensions/v3`	Address, Categories, PhoneNumber, WaypointExtension, RouteExtension, TrackExtension, RoutePointExtension, TrackPointExtension, Proximity, Temperature, Depth, DisplayMode, DisplayColor, IsAutoNamed, Subclass, rpt

Limitations

GPX 1.0 is read-only; written files always use GPX 1.1
List-type extensions (Categories, PhoneNumber) use generic element names on write; exact child-element names may differ on round-trip
Track-point-level and route-point-level extensions are lost during write because only track/route Feature objects are serialized (segment-level data is not individually written)
Subclass (hexBinary) and rpt autoroute points are parsed but not exposed via the typed API

Contributing

Please create an issue or open a pull request with a fix or enhancement.

License

MIT

Authors

Thomas Rasch, Outdooractive

Built on top of gis-tools.

Name		Name	Last commit message	Last commit date
Latest commit History 8 Commits
.github		.github
.swiftpm/xcode/package.xcworkspace		.swiftpm/xcode/package.xcworkspace
Sources/GISToolsGPX		Sources/GISToolsGPX
Tests/GISToolsGPXTests		Tests/GISToolsGPXTests
.gitignore		.gitignore
.spi.yml		.spi.yml
LICENSE		LICENSE
Package.resolved		Package.resolved
Package.swift		Package.swift
README.md		README.md

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Repository files navigation

GISToolsGPX

Features

Requirements

Installation with Swift Package Manager

Usage

Reading

Writing

Inspecting GPX element types

Waypoint properties

Track and route geometry

Garmin fitness extensions (gpxtpx)

Per-point sensor arrays (track Features only)

Converting track points to individual Features

Reconstructing a track from point features

Garmin waypoint extensions (gpxx)

Round-trip: build from scratch

Setting and writing extensions

GPX 1.0 read support

OSM traces

Raw extension access

Typed API reference

Supported extension namespaces

Limitations

Contributing

License

Authors

About

Uh oh!

Releases 5

Contributors

Uh oh!

Languages

Uh oh!

Folders and files

Latest commit

History

Repository files navigation

GISToolsGPX

Features

Requirements

Installation with Swift Package Manager

Usage

Reading

Writing

Inspecting GPX element types

Waypoint properties

Track and route geometry

Garmin fitness extensions (gpxtpx)

Per-point sensor arrays (track Features only)

Converting track points to individual Features

Reconstructing a track from point features

Garmin waypoint extensions (gpxx)

Round-trip: build from scratch

Setting and writing extensions

GPX 1.0 read support

OSM traces

Raw extension access

Typed API reference

Supported extension namespaces

Limitations

Contributing

License

Authors

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 5

Contributors

Uh oh!

Languages