---
name: gpx
displayName: GPX Track Reader & Converter
description: Read, inspect, and convert .gpx GPS track files to CSV or JSON. Use
  when opening a GPX file, extracting waypoints/tracks, or exporting route data.
tags:
  - gps
  - gpx
  - geospatial
  - converter
  - reader
  - tracks
capabilities:
  - ReadGpx
  - ConvertToCsv
  - ConvertToJson
  - ConvertToGeoJson
  - ExtractWaypoints
  - ExtractTracks
  - ExtractRoutes
  - SummarizeTracks
representativeQueries:
  - Read a .gpx file and show me its contents
  - Convert GPX tracks to CSV
  - Extract waypoints from a GPX file
  - Export GPX track points to JSON
  - Convert a GPX file to GeoJSON for use in a mapping tool
version: 0.1.0
tier: curated
---

# GPX Track Reader & Converter

Read, inspect, and convert `.gpx` GPS track files using only the Python standard library. Handles tracks, track segments, waypoints, and routes. Converts to CSV (one row per track point or waypoint) or pretty-printed JSON.

## When to use

- You have a `.gpx` file from a GPS device, fitness app (Strava, Garmin, AllTrails), or mapping tool and need to inspect its contents.
- You want to export GPS track points or waypoints to CSV for spreadsheet or database analysis.
- You need a summary of track count, total points, elevation range, or time span in a GPX file.

## Steps

1. **Detect format.** Confirm the file has a `.gpx` extension and is well-formed XML with the GPX namespace.
2. **Route by task.**
   - To read/inspect: parse the XML, extract track metadata (name, segment count, point count, elevation range, time range) and print a human-readable summary plus first N track points.
   - To convert to CSV: flatten all track points (or waypoints) into rows with lat, lon, ele, time, track name, segment index.
   - To convert to JSON: serialize extracted tracks and waypoints as a structured JSON object.
3. **Run the script.** Use `scripts/gpx_convert.py` with the file path argument and optional `--format` and `--type` flags.

## Operations

| Capability | CRUD | Resource | Tool |
|---|---|---|---|
| ReadGpx | READ | .gpx file | scripts/gpx_convert.py |
| ExtractTracks | READ | trk/trkseg/trkpt elements | scripts/gpx_convert.py |
| ExtractWaypoints | READ | wpt elements | scripts/gpx_convert.py |
| ExtractRoutes | READ | rte/rtept elements | scripts/gpx_convert.py |
| SummarizeTracks | READ | track metadata | scripts/gpx_convert.py |
| ConvertToCsv | READ + local CREATE | CSV output | scripts/gpx_convert.py |
| ConvertToJson | READ + local CREATE | JSON output | scripts/gpx_convert.py |
| ConvertToGeoJson | READ + local CREATE | GeoJSON FeatureCollection | scripts/gpx_convert.py |

## Output

- **Summary mode (default):** track count, total track points, waypoint count, elevation range (min/max), time span, and first 5 track points as formatted text.
- **CSV mode (`--format csv`):** one row per track point; columns are `track_name`, `segment_index`, `point_index`, `lat`, `lon`, `ele`, `time`. Waypoints mode (`--type waypoints`) outputs `name`, `lat`, `lon`, `ele`, `time`, `desc`, `sym`. Routes mode (`--type routes`) outputs `route_name`, `point_index`, `lat`, `lon`, `ele`, `name`.
- **JSON mode (`--format json`):** structured object with `tracks` (array of segments with point arrays), `waypoints`, and `routes` arrays, printed to stdout.
- **GeoJSON mode (`--format geojson`):** a GeoJSON FeatureCollection where track segments become LineString features, waypoints become Point features, and routes become LineString features. Each feature carries a `gpx_type` property (`track`, `waypoint`, or `route`) and relevant metadata.

## Notes

- GPX files use XML namespaces; the script strips them transparently using ElementTree.
- Elevation (`ele`) is in meters above mean sea level (orthometric height); it may be absent in some files.
- Time values are UTC ISO 8601 strings; they may be absent (e.g., manually created routes).
- A track with multiple segments usually means there were recording gaps; segments are output as separate groups in JSON and labeled with a `segment_index` in CSV.
- Vendor extension elements (heart rate, cadence) are not extracted by default; they appear in the raw XML but are ignored in converted output.
- The script exits with a non-zero code and a descriptive error message on malformed XML or missing file.

<!-- runner-fallback -->
## Remote runner (MCP)
Can't run this locally (no setup, missing dependency)? The StealthStack runner exposes the **same code** as server-side MCP tools — no local install needed: `gpx_summarize`, `gpx_to_csv`, `gpx_to_json`, `gpx_to_geojson`. Call the `application/mcp` catalog twin of this skill (its `runnerTwin`).