Simplify a GPX file or line

# Without a key, leave out the Authorization line (500 credits a day per address).
curl --fail-with-body 'https://api.trailsplits.com/v1/gpx/simplify' \
  -H "Authorization: Bearer $TRAILSPLITS_API_KEY" \
  -H 'Content-Type: application/json' \
  --data '{"geometry":{"type":"LineString","coordinates":[[12.1352,46.5369],[12.13509,46.536875],[12.13498,46.53681],[12.13487,46.536785],[12.13476,46.53672],[12.13465,46.536695],[12.13454,46.53663],[12.13443,46.536605],[12.13432,46.53654],[12.13421,46.536515],[12.1341,46.53645],[12.13399,46.536425],[12.13388,46.53636],[12.13377,46.536335],[12.13366,46.53627],[12.13355,46.536245],[12.13344,46.53618],[12.13333,46.536155],[12.13322,46.53609],[12.13311,46.536065],[12.133,46.536]]},"tolerance_m":10}'

{
  "type": "object",
  "properties": {
    "schema": {
      "type": "string",
      "enum": [
        "gpx-simplify/1"
      ]
    },
    "engine": {
      "type": "object"
    },
    "settings": {
      "type": "object"
    },
    "input": {
      "type": "object",
      "properties": {
        "format": {
          "type": "string"
        },
        "segments": {
          "type": "integer"
        },
        "points": {
          "type": "integer"
        }
      },
      "required": [
        "format",
        "segments",
        "points"
      ]
    },
    "result": {
      "type": "object",
      "properties": {
        "points": {
          "type": "integer"
        },
        "removed": {
          "type": "integer"
        },
        "max_deviation_m": {
          "type": "number",
          "nullable": true
        }
      },
      "required": [
        "points",
        "removed"
      ]
    },
    "gpx": {
      "type": "string"
    },
    "geometry": {
      "type": "object"
    }
  },
  "required": [
    "schema",
    "input",
    "result"
  ]
}

Two operations for files from watches, phones and apps:

• Clean: drop repeated points and points whose coordinates cannot be read. On request, also remove the timestamps or the sensor data (heart rate, cadence, power).
• Simplify: remove the points the route's shape and climb do not need, to fit a device's point limit or make the file small.

Both use the same rules and engine as the GPX Simplifier (src/lib/gpx-ops), so a file gives the same points here as on the page.

The file comes back as the file. Only the points removed, and on request the timestamps or sensor data, are cut out of its text. Everything else stays byte for byte: the header, metadata, waypoints, names (CDATA included), comments, the kept points with their own extras, and the indentation. A point alone on its line goes with its line, so no blank lines are left; one sharing a line goes with the spaces that separated it. An unchanged file comes back identical. Nothing is stored.

Limits

• Body: up to 5 MB, which is larger than the other products allow, so a long recording with heart rate fits.
• At most 50,000 points.
• Measured on a laptop:
  • a 50,000-point recording cleans in 0.3 s and simplifies in 0.2 to 0.3 s (one with heart rate and times on every point is 7.7 MB, over the limit: send such a file in pieces, or GeoJSON to simplify);
  • 50,000 points as GeoJSON simplify in under 0.1 s.
• A file of more than 10,000 points takes one of the worker's heavy-job slots, to clean or to simplify: either holds the worker's event loop. Beyond the worker's slots and queue the answer is 503 overloaded.

Reading a GPX

• Track points are grouped by <trkseg>. Points placed straight in a <trk> form a segment of their own.
• Route points (<rtept>) are grouped by <rte>, and are read only when the file has no track points.
• Waypoints (<wpt>) are read for their position and name.
• Prefixes: element names may carry a namespace prefix (<gpx:trkpt>).
• Comments and CDATA are not read as markup.
• Refused files: a TCX, a KML, a file without <gpx>, or a cut-off element is invalid_gpx.

POST /v1/gpx/clean

{ "gpx": "<gpx…>", "strip_times": true, "strip_extensions": true }

Response:

A time or an extension inside a point that was dropped is not counted as removed: it went with its point.

POST /v1/gpx/simplify

{ "gpx": "<gpx…>", "tolerance_m": 10 }
{ "gpx": "<gpx…>", "max_points": 1000 }
{ "geometry": { "type": "LineString", "coordinates": [[lon, lat, height?], …] }, "tolerance_m": 5 }

The rules, as on the page:

• Each segment is simplified on its own and keeps both of its ends, so a segment is never left with a single point.
• A budget smaller than the ends of every segment and every stop is refused (budget_too_small, with the minimum). The end of a route is never cut to meet the number.
• A GPX with unreadable coordinates is refused (invalid_coordinates). Clean it first: drop_bad drops them.

Response:

Measuring:

• Distance and climb are measured within each segment, never across the gap between two.
• Climb uses the house 5 m hysteresis, and is shown only when at least half of the points carry a height.
• After simplification the ascent can read a few metres more or less than before, because a 5 m threshold sees a simpler line.

Errors

{ "error": { "code", "message" } }.

Versioning

Additive fields may appear in gpx-clean/1 and gpx-simplify/1. A change of meaning or a removed field is version 2.