Skip to content

Developer API / Examples / Reference

REFERENCE · REGISTRY 1.19.0

API reference

Every call the API answers, each with a working example in curl, JavaScript and Python and a map to try it on. Every call is checked by a live probe against the public API. Weather is served from https://trailsplits.com, everything else from https://api.trailsplits.com. New fields can appear at any time; breaking changes are announced on the changelog.

Download OpenAPI JSON · TypeScript client · Postman collection (Bruno and Insomnia import it) · Working examples (ZIP)

You don't need a key to try: 500 credits a day per address. A free key from the API console counts calls against your project. Start with the quickstart; the conventions cover coordinate order, units, errors and limits. Use follows the API terms and the plan limits.

GET

Tile gateway health

/healthz

Public edge observation: text ok, not JSON. Origin paths/handlers can differ; health does not establish dataset freshness.

Full reference, examples in curl, JavaScript and Python, and Try it →

Inspect request and response shapes
Tile gateway health request
curl --fail-with-body 'https://api.trailsplits.com/healthz'

Tile gateway health contract
{
  "get": {
    "operationId": "health",
    "summary": "Tile gateway health",
    "description": "Public edge observation: text ok, not JSON. Origin paths/handlers can differ; health does not establish dataset freshness.",
    "tags": [
      "Developer preview"
    ],
    "security": [],
    "parameters": [],
    "responses": {
      "200": {
        "description": "Public gateway answers.",
        "content": {
          "text/plain": {
            "schema": {
              "type": "string",
              "enum": [
                "ok"
              ]
            }
          }
        }
      },
      "default": {
        "description": "Other gateway/provider failures are possible in preview. Consumers bound and surface them; do not treat an unknown status as success."
      }
    }
  }
}

Schema references resolve in the downloadable OpenAPI file. A shape check does not establish field accuracy or physical route suitability.

GET

Published artifact identities

/pmtiles/current/manifest.json

Resolve each artifact independently. Only the three demo-required artifact shapes are specified here; additional artifacts/metadata are retained. Missing required artifacts prevent this integration. Null/absent source dates stay unknown; retained URLs may retire.

Full reference, examples in curl, JavaScript and Python, and Try it →

Inspect request and response shapes
Published artifact identities request
curl --fail-with-body 'https://api.trailsplits.com/pmtiles/current/manifest.json'

Published artifact identities contract
{
  "get": {
    "operationId": "manifest",
    "summary": "Published artifact identities",
    "description": "Resolve each artifact independently. Only the three demo-required artifact shapes are specified here; additional artifacts/metadata are retained. Missing required artifacts prevent this integration. Null/absent source dates stay unknown; retained URLs may retire.",
    "tags": [
      "Developer preview"
    ],
    "security": [],
    "parameters": [],
    "responses": {
      "200": {
        "description": "Successful response; additive fields are allowed.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Manifest"
            }
          }
        }
      },
      "default": {
        "description": "Other gateway/provider failures are possible in preview. Consumers bound and surface them; do not treat an unknown status as success."
      }
    }
  }
}

Published artifact identities response fields
{
  "type": "object",
  "properties": {
    "artifacts": {
      "type": "object",
      "properties": {
        "basemap": {
          "$ref": "#/components/schemas/Artifact"
        },
        "terrain": {
          "$ref": "#/components/schemas/Artifact"
        },
        "styles": {
          "$ref": "#/components/schemas/StyleArtifact"
        }
      },
      "required": [
        "basemap",
        "terrain",
        "styles"
      ],
      "additionalProperties": true
    }
  },
  "required": [
    "artifacts"
  ],
  "additionalProperties": true
}

Schema references resolve in the downloadable OpenAPI file. A shape check does not establish field accuracy or physical route suitability.

GET

Artifact status verdict

/tiles/v1/status

artifact-status/1 producer verdict. Source-bound fresh can have a null source date; available=false is an unavailable manifest, not proof of freshness. Unknown is distinct from stale.

Full reference, examples in curl, JavaScript and Python, and Try it →

Inspect request and response shapes
Artifact status verdict request
curl --fail-with-body 'https://api.trailsplits.com/tiles/v1/status'

Artifact status verdict contract
{
  "get": {
    "operationId": "status",
    "summary": "Artifact status verdict",
    "description": "artifact-status/1 producer verdict. Source-bound fresh can have a null source date; available=false is an unavailable manifest, not proof of freshness. Unknown is distinct from stale.",
    "tags": [
      "Developer preview"
    ],
    "security": [],
    "parameters": [],
    "responses": {
      "200": {
        "description": "Successful response; additive fields are allowed.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Status"
            }
          }
        }
      },
      "500": {
        "description": "Documented error/refusal; no result geometry should be fabricated.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "default": {
        "description": "Other gateway/provider failures are possible in preview. Consumers bound and surface them; do not treat an unknown status as success."
      }
    }
  }
}

Artifact status verdict response fields
{
  "type": "object",
  "properties": {
    "schema": {
      "type": "string",
      "enum": [
        "artifact-status/1"
      ]
    },
    "checked_at": {
      "type": "string"
    },
    "available": {
      "type": "boolean"
    },
    "stale": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "artifacts": {
      "type": "object",
      "additionalProperties": {
        "$ref": "#/components/schemas/StatusEntry"
      }
    }
  },
  "required": [
    "schema",
    "checked_at",
    "available",
    "stale",
    "artifacts"
  ],
  "additionalProperties": true
}

Schema references resolve in the downloadable OpenAPI file. A shape check does not establish field accuracy or physical route suitability.

GET

Terrain pixel sampling

/tiles/v1/elevation/{release}/sample

Pipe-separated lat,lon. Producer accepts up to 2048 points, clamps requested zoom to available backing data and returns one modelled metre height per point. null is missing, never zero. Does not densify or smooth a line. Example consumers impose smaller bounds. Unknown accuracy/source resolution is not surveyed truth.

Parameters
Name / locationContract
release · path · requiredPublished terrain version, or mutable current. Demo resolves/pins a version.
points · query · required1–2048 lat,lon pairs separated by |; example uses 8/16/32.
z · queryRequested zoom; response z is the effective zoom.
encoding · queryUse mapbox for the published terrain. Other encoding is compatibility input, not a second dataset.

Run the elevation profile example to see heights and unknown gaps.

Full reference, examples in curl, JavaScript and Python, and Try it →

Inspect request and response shapes
Terrain pixel sampling request
# Replace TERRAIN_RELEASE with artifacts.terrain.version from the manifest.
curl --fail-with-body 'https://api.trailsplits.com/tiles/v1/elevation/TERRAIN_RELEASE/sample?points=46.5369000%2C12.1352000%7C46.5367714%2C12.1348857%7C46.5366429%2C12.1345714%7C46.5365143%2C12.1342571%7C46.5363857%2C12.1339429%7C46.5362571%2C12.1336286%7C46.5361286%2C12.1333143%7C46.5360000%2C12.1330000&z=12&encoding=mapbox'

Terrain pixel sampling contract
{
  "get": {
    "operationId": "elevation",
    "summary": "Terrain pixel sampling",
    "description": "Pipe-separated lat,lon. Producer accepts up to 2048 points, clamps requested zoom to available backing data and returns one modelled metre height per point. null is missing, never zero. Does not densify or smooth a line. Example consumers impose smaller bounds. Unknown accuracy/source resolution is not surveyed truth.",
    "tags": [
      "Developer preview"
    ],
    "security": [
      {},
      {
        "ApiKey": []
      }
    ],
    "parameters": [
      {
        "name": "release",
        "in": "path",
        "required": true,
        "schema": {
          "type": "string"
        },
        "description": "Published terrain version, or mutable current. Demo resolves/pins a version."
      },
      {
        "name": "points",
        "in": "query",
        "required": true,
        "schema": {
          "type": "string"
        },
        "description": "1–2048 lat,lon pairs separated by |; example uses 8/16/32."
      },
      {
        "name": "z",
        "in": "query",
        "required": false,
        "schema": {
          "type": "integer",
          "minimum": 0,
          "maximum": 22,
          "default": 13
        },
        "description": "Requested zoom; response z is the effective zoom."
      },
      {
        "name": "encoding",
        "in": "query",
        "required": false,
        "schema": {
          "type": "string",
          "enum": [
            "mapbox",
            "terrarium"
          ],
          "default": "mapbox"
        },
        "description": "Use mapbox for the published terrain. Other encoding is compatibility input, not a second dataset."
      }
    ],
    "responses": {
      "200": {
        "description": "Successful response; additive fields are allowed.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Elevation"
            }
          }
        }
      },
      "400": {
        "description": "Documented error/refusal; no result geometry should be fabricated.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "404": {
        "description": "Documented error/refusal; no result geometry should be fabricated.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "500": {
        "description": "Documented error/refusal; no result geometry should be fabricated.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "default": {
        "description": "Other gateway/provider failures are possible in preview. Consumers bound and surface them; do not treat an unknown status as success."
      }
    }
  }
}

Terrain pixel sampling response fields
{
  "type": "object",
  "properties": {
    "release": {
      "type": "string"
    },
    "z": {
      "type": "integer",
      "minimum": 0,
      "maximum": 22
    },
    "z_requested": {
      "type": "integer"
    },
    "encoding": {
      "type": "string",
      "enum": [
        "mapbox",
        "terrarium"
      ]
    },
    "points": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "lat": {
            "type": "number"
          },
          "lon": {
            "type": "number"
          },
          "elevation_m": {
            "type": "number",
            "nullable": true
          }
        },
        "required": [
          "lat",
          "lon",
          "elevation_m"
        ],
        "additionalProperties": true
      }
    }
  },
  "required": [
    "release",
    "z",
    "encoding",
    "points"
  ],
  "additionalProperties": true
}

Schema references resolve in the downloadable OpenAPI file. A shape check does not establish field accuracy or physical route suitability.

GET

Point and batch weather forecast

https://trailsplits.com/api/weather/forecast· served from the main site, not the API host

Served from the main site, not the API host. Daily values per point and local date; each day names its model and issued_at is the model run (null with a reason when unknown, never the fetch time). Missing values are null, never 0; fewer days or fields than asked is state partial with reasons. Pass each point height: a model cell height can be a thousand metres off in the mountains. Attribution from provider.attribution (Open-Meteo, CC BY 4.0) is required wherever values are shown.

Parameters
Name / locationContract
p · query · required1–12 points as lat,lon[,elevation_m] separated by ;. Coordinates are rounded to 2 decimals (about 1 km) and echoed rounded.
d · queryForecast days.
fl · queryAdd the hourly freezing level.
h · queryAdd hourly[] per point over the requested days (about 130 bytes per hour and point; ask only for the days you need). Any other value is 400.

Read the weather guide for models, heights and attribution. The downloadable examples include weather.mjs.

Full reference, examples in curl, JavaScript and Python, and Try it →

Inspect request and response shapes
Point and batch weather forecast request
curl --fail-with-body 'https://trailsplits.com/api/weather/forecast?p=46.0207,7.7491,1608&d=2'

Point and batch weather forecast contract
{
  "servers": [
    {
      "url": "https://trailsplits.com",
      "description": "Main site; this operation is not on the API host."
    }
  ],
  "get": {
    "operationId": "weather",
    "summary": "Point and batch weather forecast",
    "description": "Served from the main site, not the API host. Daily values per point and local date; each day names its model and issued_at is the model run (null with a reason when unknown, never the fetch time). Missing values are null, never 0; fewer days or fields than asked is state partial with reasons. Pass each point height: a model cell height can be a thousand metres off in the mountains. Attribution from provider.attribution (Open-Meteo, CC BY 4.0) is required wherever values are shown.",
    "tags": [
      "Developer preview"
    ],
    "security": [],
    "parameters": [
      {
        "name": "p",
        "in": "query",
        "required": true,
        "schema": {
          "type": "string"
        },
        "description": "1–12 points as lat,lon[,elevation_m] separated by ;. Coordinates are rounded to 2 decimals (about 1 km) and echoed rounded."
      },
      {
        "name": "d",
        "in": "query",
        "required": false,
        "schema": {
          "type": "integer",
          "minimum": 1,
          "maximum": 16,
          "default": 7
        },
        "description": "Forecast days."
      },
      {
        "name": "fl",
        "in": "query",
        "required": false,
        "schema": {
          "type": "integer",
          "enum": [
            1
          ]
        },
        "description": "Add the hourly freezing level."
      },
      {
        "name": "h",
        "in": "query",
        "required": false,
        "schema": {
          "type": "integer",
          "enum": [
            1
          ]
        },
        "description": "Add hourly[] per point over the requested days (about 130 bytes per hour and point; ask only for the days you need). Any other value is 400."
      }
    ],
    "responses": {
      "200": {
        "description": "Successful response; additive fields are allowed.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/WeatherForecast"
            }
          }
        }
      },
      "400": {
        "description": "Documented error/refusal; no result geometry should be fabricated.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "503": {
        "description": "Documented error/refusal; no result geometry should be fabricated.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "default": {
        "description": "Other gateway/provider failures are possible in preview. Consumers bound and surface them; do not treat an unknown status as success."
      }
    }
  }
}

Point and batch weather forecast response fields
{
  "type": "object",
  "properties": {
    "schema": {
      "type": "string",
      "enum": [
        "weather-forecast/1"
      ]
    },
    "provider": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string"
        },
        "model": {
          "type": "string"
        },
        "attribution": {
          "type": "string"
        },
        "licence": {
          "type": "string"
        }
      },
      "required": [
        "attribution",
        "licence"
      ],
      "additionalProperties": true
    },
    "fetched_at": {
      "type": "string"
    },
    "issued_at": {
      "type": "string",
      "nullable": true,
      "description": "The model run, or null with issued_at_reason. Never the fetch time."
    },
    "issued_at_reason": {
      "type": "string",
      "nullable": true
    },
    "fresh_until": {
      "type": "string"
    },
    "requested_days": {
      "type": "integer",
      "minimum": 1,
      "maximum": 16
    },
    "points": {
      "type": "array",
      "minItems": 1,
      "maxItems": 12,
      "items": {
        "$ref": "#/components/schemas/WeatherPoint"
      }
    }
  },
  "required": [
    "schema",
    "provider",
    "fetched_at",
    "issued_at",
    "fresh_until",
    "requested_days",
    "points"
  ],
  "additionalProperties": true
}

Schema references resolve in the downloadable OpenAPI file. A shape check does not establish field accuracy or physical route suitability.

POST

Analyse a route you already have

/v1/route-analysis

Send a GPX or GeoJSON line (at most 1 MB, 5,000 points, 300 km). The answer places it on the mapped network and says on what surface it runs, which OpenStreetMap grades are tagged, how much it climbs (method named), how long a hike takes with the model scope, and every unknown. The line you send is never rewritten, and nothing is drawn across a gap. Untagged paths are unknown, never easy. No geometry is kept after the answer.

Read the route analysis guide; the downloadable examples include analysis.mjs.

Full reference, examples in curl, JavaScript and Python, and Try it →

Inspect request and response shapes
Analyse a route you already have request
curl --fail-with-body 'https://api.trailsplits.com/v1/route-analysis' \
  -H 'Content-Type: application/json' \
  --data '{"geometry":{"type":"LineString","coordinates":[[12.1352,46.5369],[12.133,46.536]]},"profile":"hike"}'

Analyse a route you already have contract
{
  "post": {
    "operationId": "route-analysis",
    "summary": "Analyse a route you already have",
    "description": "Send a GPX or GeoJSON line (at most 1 MB, 5,000 points, 300 km). The answer places it on the mapped network and says on what surface it runs, which OpenStreetMap grades are tagged, how much it climbs (method named), how long a hike takes with the model scope, and every unknown. The line you send is never rewritten, and nothing is drawn across a gap. Untagged paths are unknown, never easy. No geometry is kept after the answer.",
    "tags": [
      "Developer preview"
    ],
    "security": [
      {},
      {
        "ApiKey": []
      }
    ],
    "parameters": [],
    "requestBody": {
      "required": true,
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/RouteAnalysisInput"
          }
        }
      }
    },
    "responses": {
      "200": {
        "description": "Successful response; additive fields are allowed.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/RouteAnalysis"
            }
          }
        }
      },
      "400": {
        "description": "Documented error/refusal; no result geometry should be fabricated.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ProductError"
            }
          }
        }
      },
      "413": {
        "description": "Documented error/refusal; no result geometry should be fabricated.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ProductError"
            }
          }
        }
      },
      "422": {
        "description": "Documented error/refusal; no result geometry should be fabricated.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ProductError"
            }
          }
        }
      },
      "default": {
        "description": "Other gateway/provider failures are possible in preview. Consumers bound and surface them; do not treat an unknown status as success."
      }
    }
  }
}

Analyse a route you already have response fields
{
  "type": "object",
  "properties": {
    "schema": {
      "type": "string",
      "enum": [
        "route-analysis/1"
      ]
    },
    "engine": {
      "type": "object",
      "additionalProperties": true
    },
    "profile": {
      "type": "string"
    },
    "input": {
      "type": "object",
      "properties": {
        "format": {
          "type": "string"
        },
        "parts": {
          "type": "integer"
        },
        "points": {
          "type": "integer"
        },
        "length_m": {
          "type": "number"
        }
      },
      "required": [
        "format",
        "parts",
        "points",
        "length_m"
      ],
      "additionalProperties": true
    },
    "match": {
      "type": "object",
      "properties": {
        "status": {
          "type": "string",
          "enum": [
            "matched",
            "partial",
            "unmatched"
          ]
        },
        "coverage": {
          "type": "number"
        },
        "trace_length_m": {
          "type": "number"
        },
        "matched_length_m": {
          "type": "number"
        },
        "network_length_m": {
          "type": "number"
        },
        "segments": {
          "type": "array",
          "items": {
            "type": "object",
            "additionalProperties": true
          }
        },
        "unmatched": {
          "type": "array",
          "items": {
            "type": "object",
            "additionalProperties": true
          }
        }
      },
      "required": [
        "status",
        "coverage",
        "trace_length_m",
        "matched_length_m",
        "network_length_m",
        "segments",
        "unmatched"
      ],
      "additionalProperties": true
    },
    "surfaces": {
      "type": "object",
      "nullable": true,
      "additionalProperties": true
    },
    "ways": {
      "type": "object",
      "nullable": true,
      "additionalProperties": true
    },
    "difficulty": {
      "type": "object",
      "nullable": true,
      "additionalProperties": true,
      "description": "Tagged sac_scale per length; untagged paths are unknown, never easy."
    },
    "elevation": {
      "type": "object",
      "nullable": true,
      "additionalProperties": true
    },
    "time": {
      "type": "object",
      "nullable": true,
      "additionalProperties": true,
      "description": "Hike only: trailsplits-hike/2 moving time, its scope and outside_calibration, region (countries crossed and their calibration_legs) and notes; profile: cumulative minutes along the line (at most 500 [m, min], ending at minutes); with a pace_profile, personal { minutes, interval_80, base_version, factors, activities, profile }; models[]: every named model with id, minutes, label and note, and convention: a publisher’s own signpost convention where the line lies in its area (trailsplits-hike-published/1: SAT in Trentino, with its factors, interval_80, held-out check, licence and attribution), else null with the label “No published convention here”. minutes stays the TrailSplits model’s; null for run and bike."
    },
    "sections": {
      "type": "object",
      "nullable": true,
      "additionalProperties": true,
      "description": "Only with sections: true. The course-sections/1 record (segmentation_version, height_method, totals, terrain[], findings, legs, line_source visitor-file) plus heights_source (terrain or recorded). On terrain heights totals.ascent_m equals elevation.ascent_m. Null with the unknown sections_unavailable when the line has no heights."
    },
    "unknowns": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "code": {
            "type": "string"
          },
          "message": {
            "type": "string"
          }
        },
        "required": [
          "code",
          "message"
        ],
        "additionalProperties": true
      }
    }
  },
  "required": [
    "schema",
    "engine",
    "profile",
    "input",
    "match",
    "unknowns"
  ],
  "additionalProperties": true
}

Analyse a route you already have request fields
{
  "type": "object",
  "properties": {
    "gpx": {
      "type": "string",
      "description": "A GPX 1.0/1.1 document; each trkseg (else rte) is a part. Exactly one of gpx and geometry."
    },
    "geometry": {
      "type": "object",
      "additionalProperties": true,
      "description": "GeoJSON LineString, MultiLineString, a Feature of either, or a FeatureCollection of them; a third coordinate is a height."
    },
    "profile": {
      "type": "string",
      "enum": [
        "hike",
        "run",
        "bike"
      ],
      "default": "hike"
    },
    "elevation": {
      "type": "string",
      "enum": [
        "auto",
        "recorded",
        "terrain"
      ],
      "default": "auto"
    },
    "sections": {
      "type": "boolean",
      "default": false,
      "description": "True adds sections: the line’s course sections (course-sections/1: climbs, descents, connectors, the largest continuous ascent, the steepest 500 m and 1 km), cut from the heights this answer reads. Added 6 October 2026."
    },
    "pace_profile": {
      "type": "object",
      "additionalProperties": true,
      "description": "Hike only: the pace_profile /v1/time-model/fit answered, sent unchanged. Adds the person’s own time (with an 80 % range) beside the model’s; refused with 422 pace_profile_stale after a refit of the model."
    }
  },
  "additionalProperties": true
}

Schema references resolve in the downloadable OpenAPI file. A shape check does not establish field accuracy or physical route suitability.

POST

Round trips from a start point

/v1/roundtrips

Loops that start and end at a point, from the same engine as the TrailSplits Planner. Each loop reports its target error, the distance walked twice and the same facts as route analysis. Status complete means within 10 % of the target with at most 20 % repeated; rough is answered with a reason; when no good loop exists the answer is 422 no_loop, never an invented loop. Limits: 0.5–40 km on foot, 0.5–60 km by bike (422 too_long), up to 3 alternatives. strategy ring or auto adds waypoint rings routed on the same graph; each loop says which engine made it and how it scores (length fit, clean, marked).

Read the round trips guide; the downloadable examples include roundtrip.mjs.

Full reference, examples in curl, JavaScript and Python, and Try it →

Inspect request and response shapes
Round trips from a start point request
curl --fail-with-body 'https://api.trailsplits.com/v1/roundtrips' \
  -H 'Content-Type: application/json' \
  --data '{"start":[7.7491,46.0207],"distance_km":12,"profile":"hike"}'

Round trips from a start point contract
{
  "post": {
    "operationId": "roundtrips",
    "summary": "Round trips from a start point",
    "description": "Loops that start and end at a point, from the same engine as the TrailSplits Planner. Each loop reports its target error, the distance walked twice and the same facts as route analysis. Status complete means within 10 % of the target with at most 20 % repeated; rough is answered with a reason; when no good loop exists the answer is 422 no_loop, never an invented loop. Limits: 0.5–40 km on foot, 0.5–60 km by bike (422 too_long), up to 3 alternatives. strategy ring or auto adds waypoint rings routed on the same graph; each loop says which engine made it and how it scores (length fit, clean, marked).",
    "tags": [
      "Developer preview"
    ],
    "security": [
      {},
      {
        "ApiKey": []
      }
    ],
    "parameters": [],
    "requestBody": {
      "required": true,
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/RoundtripsInput"
          }
        }
      }
    },
    "responses": {
      "200": {
        "description": "Successful response; additive fields are allowed.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Roundtrips"
            }
          }
        }
      },
      "400": {
        "description": "Documented error/refusal; no result geometry should be fabricated.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ProductError"
            }
          }
        }
      },
      "422": {
        "description": "Documented error/refusal; no result geometry should be fabricated.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ProductError"
            }
          }
        }
      },
      "default": {
        "description": "Other gateway/provider failures are possible in preview. Consumers bound and surface them; do not treat an unknown status as success."
      }
    }
  }
}

Round trips from a start point response fields
{
  "type": "object",
  "properties": {
    "schema": {
      "type": "string",
      "enum": [
        "roundtrips/1"
      ]
    },
    "engine": {
      "type": "object",
      "additionalProperties": true
    },
    "status": {
      "type": "string",
      "enum": [
        "complete",
        "rough"
      ]
    },
    "reason": {
      "type": "string",
      "nullable": true
    },
    "strategy": {
      "type": "string",
      "enum": [
        "graph",
        "ring",
        "auto"
      ],
      "description": "The strategy used."
    },
    "request": {
      "type": "object",
      "additionalProperties": true
    },
    "search": {
      "type": "object",
      "additionalProperties": true,
      "description": "The engine’s counters; version skipped with strategy ring. With rings, ring: probes, routed, kept, ms, stopped."
    },
    "loops": {
      "type": "array",
      "minItems": 1,
      "maxItems": 4,
      "items": {
        "type": "object",
        "properties": {
          "rank": {
            "type": "integer"
          },
          "status": {
            "type": "string",
            "enum": [
              "complete",
              "rough"
            ]
          },
          "engine": {
            "type": "string",
            "enum": [
              "graph",
              "ring"
            ],
            "description": "Where this loop came from."
          },
          "score": {
            "type": "object",
            "properties": {
              "length_fit": {
                "type": "number"
              },
              "clean": {
                "type": "number"
              },
              "marked": {
                "type": "number",
                "nullable": true,
                "description": "Null for bike."
              },
              "total": {
                "type": "number"
              }
            },
            "required": [
              "length_fit",
              "clean",
              "marked",
              "total"
            ],
            "additionalProperties": true
          },
          "quality": {
            "type": "number",
            "nullable": true,
            "description": "Cost per metre over the best ground; null for a ring loop."
          },
          "distance_m": {
            "type": "number"
          },
          "target_m": {
            "type": "number"
          },
          "target_error_pct": {
            "type": "number"
          },
          "repeated_m": {
            "type": "number"
          },
          "repeated_share": {
            "type": "number"
          },
          "second_pass_share": {
            "type": "number",
            "description": "The share walked a second time by geometry, 0–1; status and score.clean read the larger of this and repeated_share."
          },
          "shape": {
            "type": "string",
            "description": "Polyline6."
          },
          "ascent_m": {
            "type": "number",
            "nullable": true
          },
          "time": {
            "type": "object",
            "nullable": true,
            "additionalProperties": true
          }
        },
        "required": [
          "rank",
          "status",
          "distance_m",
          "target_m",
          "target_error_pct",
          "repeated_share",
          "shape"
        ],
        "additionalProperties": true
      }
    }
  },
  "required": [
    "schema",
    "engine",
    "status",
    "loops"
  ],
  "additionalProperties": true
}

Round trips from a start point request fields
{
  "type": "object",
  "properties": {
    "start": {
      "type": "array",
      "minItems": 2,
      "maxItems": 2,
      "items": {
        "type": "number"
      },
      "description": "[lon, lat]"
    },
    "distance_km": {
      "type": "number",
      "minimum": 0.5,
      "maximum": 60,
      "description": "0.5–40 km for hike and run, to 60 km for bike. Or distance_m, not both."
    },
    "distance_m": {
      "type": "number"
    },
    "profile": {
      "type": "string",
      "enum": [
        "hike",
        "run",
        "bike"
      ],
      "default": "hike"
    },
    "direction": {
      "type": "number",
      "nullable": true
    },
    "alternatives": {
      "type": "integer",
      "minimum": 0,
      "maximum": 3,
      "default": 0
    },
    "max_sac": {
      "type": "integer",
      "minimum": 1,
      "maximum": 6,
      "default": 3
    },
    "avoid_paved": {
      "type": "boolean"
    },
    "hills": {
      "type": "number",
      "minimum": -1,
      "maximum": 1
    },
    "bicycle_type": {
      "type": "string",
      "enum": [
        "road",
        "hybrid",
        "mountain"
      ]
    },
    "strategy": {
      "type": "string",
      "enum": [
        "graph",
        "ring",
        "auto"
      ],
      "default": "graph",
      "description": "Where the loops come from. graph: the loop search on the routing graph. ring: waypoint rings through the start routed on the same graph (up to 24 probes). auto: the graph first, rings when its loop is rough or missing, all ranked together."
    },
    "climb_target": {
      "type": "object",
      "properties": {
        "ascent_m": {
          "type": "number",
          "minimum": 50,
          "maximum": 2500
        },
        "distance_m": {
          "type": "number",
          "minimum": 200,
          "maximum": 30000
        },
        "grade_pct": {
          "type": "number",
          "minimum": 1,
          "maximum": 50
        }
      },
      "required": [
        "ascent_m"
      ],
      "additionalProperties": true,
      "description": "hike and run: a continuous climb to rehearse (a race's largest ascent). Summit rings join the candidates, loops are ordered by how well their largest continuous ascent reproduces it, and each loop gets a climb_target verdict."
    }
  },
  "required": [
    "start"
  ],
  "additionalProperties": true
}

Schema references resolve in the downloadable OpenAPI file. A shape check does not establish field accuracy or physical route suitability.

POST

Weather along a route at arrival time

/v1/route-weather

Send one line, a departure with its offset and a pace. Samples every 2 km plus the start, end and marked highs and lows each get the forecast at the hour you reach them, at their own terrain height, with the model named per hour. Missing stays missing (weather null with a reason). Sections give ranges, never a combined safety score. Hike uses the calibrated trailsplits-hike/2 time; run and bike need your own pace. Limits: one part, 5,000 points, 120 km, 1 MB; departure from six hours ago to 16 days ahead. With sun: true it also says where the line is in sun or shade when you get there (terrain shadow from a 30 m model; the state is right about 97 % of the time against lidar, and no time the sun comes or goes is given), and each sample’s sunrise and sunset.

Read the route weather guide; the downloadable examples include routeweather.mjs.

Full reference, examples in curl, JavaScript and Python, and Try it →

Inspect request and response shapes
Weather along a route at arrival time request
curl --fail-with-body 'https://api.trailsplits.com/v1/route-weather' \
  -H 'Content-Type: application/json' \
  --data '{"geometry":{"type":"LineString","coordinates":[[12.1352,46.5369],[12.133,46.536]]},"departure":"2026-10-03T08:00:00+02:00","profile":"hike"}'
# Set departure inside the next 16 days.

Weather along a route at arrival time contract
{
  "post": {
    "operationId": "route-weather",
    "summary": "Weather along a route at arrival time",
    "description": "Send one line, a departure with its offset and a pace. Samples every 2 km plus the start, end and marked highs and lows each get the forecast at the hour you reach them, at their own terrain height, with the model named per hour. Missing stays missing (weather null with a reason). Sections give ranges, never a combined safety score. Hike uses the calibrated trailsplits-hike/2 time; run and bike need your own pace. Limits: one part, 5,000 points, 120 km, 1 MB; departure from six hours ago to 16 days ahead. With sun: true it also says where the line is in sun or shade when you get there (terrain shadow from a 30 m model; the state is right about 97 % of the time against lidar, and no time the sun comes or goes is given), and each sample’s sunrise and sunset.",
    "tags": [
      "Developer preview"
    ],
    "security": [
      {},
      {
        "ApiKey": []
      }
    ],
    "parameters": [],
    "requestBody": {
      "required": true,
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/RouteWeatherInput"
          }
        }
      }
    },
    "responses": {
      "200": {
        "description": "Successful response; additive fields are allowed.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/RouteWeather"
            }
          }
        }
      },
      "400": {
        "description": "Documented error/refusal; no result geometry should be fabricated.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ProductError"
            }
          }
        }
      },
      "413": {
        "description": "Documented error/refusal; no result geometry should be fabricated.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ProductError"
            }
          }
        }
      },
      "422": {
        "description": "Documented error/refusal; no result geometry should be fabricated.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ProductError"
            }
          }
        }
      },
      "502": {
        "description": "Documented error/refusal; no result geometry should be fabricated.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ProductError"
            }
          }
        }
      },
      "503": {
        "description": "Documented error/refusal; no result geometry should be fabricated.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ProductError"
            }
          }
        }
      },
      "default": {
        "description": "Other gateway/provider failures are possible in preview. Consumers bound and surface them; do not treat an unknown status as success."
      }
    }
  }
}

Weather along a route at arrival time response fields
{
  "type": "object",
  "properties": {
    "schema": {
      "type": "string",
      "enum": [
        "route-weather/1"
      ]
    },
    "engine": {
      "type": "object",
      "additionalProperties": true
    },
    "departure": {
      "type": "object",
      "properties": {
        "given": {
          "type": "string"
        },
        "utc": {
          "type": "string"
        }
      },
      "required": [
        "given",
        "utc"
      ],
      "additionalProperties": true
    },
    "profile": {
      "type": "string"
    },
    "pace": {
      "type": "object",
      "additionalProperties": true
    },
    "forecast": {
      "type": "object",
      "properties": {
        "schema": {
          "type": "string"
        },
        "provider": {
          "type": "object",
          "properties": {
            "attribution": {
              "type": "string"
            },
            "licence": {
              "type": "string"
            }
          },
          "required": [
            "attribution"
          ],
          "additionalProperties": true
        },
        "issued_at": {
          "type": "string",
          "nullable": true
        }
      },
      "required": [
        "provider"
      ],
      "additionalProperties": true
    },
    "samples": {
      "type": "array",
      "minItems": 2,
      "items": {
        "type": "object",
        "properties": {
          "at_m": {
            "type": "number"
          },
          "kind": {
            "type": "string",
            "enum": [
              "start",
              "end",
              "high",
              "low",
              "along"
            ]
          },
          "minutes": {
            "type": "number"
          },
          "arrival_utc": {
            "type": "string"
          },
          "arrival_local": {
            "type": "string"
          },
          "forecast_elevation_m": {
            "type": "number",
            "nullable": true
          },
          "weather": {
            "type": "object",
            "nullable": true,
            "additionalProperties": true,
            "description": "The forecast hour reached; each hour names its model. Null with missing when the forecast does not hold it. Carries apparent_temp_c (feels like), cape_jkg and lightning_potential_jkg with lightning_model: model output only, and a null lightning value never means none."
          },
          "missing": {
            "type": "string",
            "nullable": true
          },
          "daylight": {
            "type": "object",
            "additionalProperties": true,
            "description": "With sun: true, the local day’s sunrise, sunset and civil twilight at the sample."
          }
        },
        "required": [
          "at_m",
          "kind",
          "minutes",
          "arrival_utc",
          "weather",
          "missing"
        ],
        "additionalProperties": true
      }
    },
    "sections": {
      "type": "array",
      "items": {
        "type": "object",
        "additionalProperties": true
      }
    },
    "sun": {
      "type": "object",
      "additionalProperties": true,
      "description": "With sun: true: points about every 200 m with the sun’s altitude and azimuth, the terrain horizon toward it, state (sun, shade, borderline, sun_down) and light, plus stretches and shares. The state is right about 97 % of the time against lidar; no time the sun comes or goes is given."
    },
    "unknowns": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "code": {
            "type": "string"
          },
          "message": {
            "type": "string"
          }
        },
        "required": [
          "code",
          "message"
        ],
        "additionalProperties": true
      }
    }
  },
  "required": [
    "schema",
    "engine",
    "departure",
    "forecast",
    "samples",
    "sections",
    "unknowns"
  ],
  "additionalProperties": true
}

Weather along a route at arrival time request fields
{
  "type": "object",
  "properties": {
    "gpx": {
      "type": "string"
    },
    "geometry": {
      "type": "object",
      "additionalProperties": true,
      "description": "One part only (a LineString); as for route analysis. Limits: 5,000 points, 120 km, 1 MB."
    },
    "departure": {
      "type": "string",
      "description": "ISO 8601 with offset, from six hours ago to 16 days ahead."
    },
    "profile": {
      "type": "string",
      "enum": [
        "hike",
        "run",
        "bike"
      ],
      "default": "hike"
    },
    "pace_factor": {
      "type": "number",
      "minimum": 0.5,
      "maximum": 2
    },
    "min_per_km": {
      "type": "number",
      "minimum": 1,
      "maximum": 60
    },
    "kmh": {
      "type": "number"
    },
    "stops": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "at_km": {
            "type": "number"
          },
          "minutes": {
            "type": "number"
          }
        },
        "required": [
          "at_km",
          "minutes"
        ],
        "additionalProperties": true
      }
    },
    "freezing_level": {
      "type": "boolean"
    },
    "sun": {
      "type": "boolean",
      "default": false,
      "description": "Adds sun and shade along the route at the time you reach each part, and each sample’s sunrise, sunset and civil twilight. Same credits."
    },
    "pace_profile": {
      "type": "object",
      "additionalProperties": true,
      "description": "Hike only: the pace_profile /v1/time-model/fit answered, sent unchanged. Adds the person’s own time (with an 80 % range) beside the model’s; refused with 422 pace_profile_stale after a refit of the model."
    }
  },
  "required": [
    "departure"
  ],
  "additionalProperties": true
}

Schema references resolve in the downloadable OpenAPI file. A shape check does not establish field accuracy or physical route suitability.

POST

Elevation profile of a line

/v1/elevation-profile

The series a chart draws for a GPX or GeoJSON line: distance, height, grade and position at each point, as rows under named columns, with ascent, descent, extremes and the steepest stretches read from the same series (method named). Terrain heights by default, or the file's own heights when they pass the check. Each part of a file is its own run; nothing is drawn across a gap. Limits: 5,000 points, 300 km, 1 MB.

Full reference, examples in curl, JavaScript and Python, and Try it →

Inspect request and response shapes
Elevation profile of a line request
curl --fail-with-body 'https://api.trailsplits.com/v1/elevation-profile' \
  -H 'Content-Type: application/json' \
  --data '{"geometry":{"type":"LineString","coordinates":[[12.1352,46.5369],[12.133,46.536]]},"points":50}'

Elevation profile of a line contract
{
  "post": {
    "operationId": "elevation-profile",
    "summary": "Elevation profile of a line",
    "description": "The series a chart draws for a GPX or GeoJSON line: distance, height, grade and position at each point, as rows under named columns, with ascent, descent, extremes and the steepest stretches read from the same series (method named). Terrain heights by default, or the file's own heights when they pass the check. Each part of a file is its own run; nothing is drawn across a gap. Limits: 5,000 points, 300 km, 1 MB.",
    "tags": [
      "Developer preview"
    ],
    "security": [
      {},
      {
        "ApiKey": []
      }
    ],
    "parameters": [],
    "requestBody": {
      "required": true,
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ElevationProfileInput"
          }
        }
      }
    },
    "responses": {
      "200": {
        "description": "Successful response; additive fields are allowed.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ElevationProfile"
            }
          }
        }
      },
      "400": {
        "description": "Documented error/refusal; no result geometry should be fabricated.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ProductError"
            }
          }
        }
      },
      "413": {
        "description": "Documented error/refusal; no result geometry should be fabricated.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ProductError"
            }
          }
        }
      },
      "422": {
        "description": "Documented error/refusal; no result geometry should be fabricated.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ProductError"
            }
          }
        }
      },
      "default": {
        "description": "Other gateway/provider failures are possible in preview. Consumers bound and surface them; do not treat an unknown status as success."
      }
    }
  }
}

Elevation profile of a line response fields
{
  "type": "object",
  "properties": {
    "schema": {
      "type": "string",
      "enum": [
        "elevation-profile/1"
      ]
    },
    "engine": {
      "type": "object",
      "additionalProperties": true
    },
    "input": {
      "type": "object",
      "properties": {
        "points": {
          "type": "integer"
        },
        "length_m": {
          "type": "number"
        }
      },
      "required": [
        "points",
        "length_m"
      ],
      "additionalProperties": true
    },
    "elevation": {
      "type": "object",
      "properties": {
        "source": {
          "type": "string",
          "enum": [
            "terrain",
            "recorded"
          ]
        },
        "method": {
          "type": "string"
        },
        "ascent_m": {
          "type": "number"
        },
        "descent_m": {
          "type": "number"
        },
        "min_m": {
          "type": "number"
        },
        "max_m": {
          "type": "number"
        }
      },
      "required": [
        "source",
        "method",
        "ascent_m",
        "descent_m"
      ],
      "additionalProperties": true
    },
    "series": {
      "type": "object",
      "properties": {
        "columns": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "distance_m, elevation_m, grade_pct, lon, lat"
        },
        "heights": {
          "type": "string"
        },
        "parts": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "from_m": {
                "type": "number"
              },
              "to_m": {
                "type": "number"
              },
              "first": {
                "type": "integer"
              },
              "last": {
                "type": "integer"
              }
            },
            "required": [
              "from_m",
              "to_m",
              "first",
              "last"
            ],
            "additionalProperties": true
          }
        },
        "points": {
          "type": "array",
          "items": {
            "type": "array",
            "items": {
              "type": "number",
              "nullable": true
            }
          }
        }
      },
      "required": [
        "columns",
        "parts",
        "points"
      ],
      "additionalProperties": true
    },
    "unknowns": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "code": {
            "type": "string"
          },
          "message": {
            "type": "string"
          }
        },
        "required": [
          "code",
          "message"
        ],
        "additionalProperties": true
      }
    }
  },
  "required": [
    "schema",
    "engine",
    "input",
    "elevation",
    "series",
    "unknowns"
  ],
  "additionalProperties": true
}

Elevation profile of a line request fields
{
  "type": "object",
  "properties": {
    "gpx": {
      "type": "string"
    },
    "geometry": {
      "type": "object",
      "additionalProperties": true,
      "description": "A GeoJSON line, as for route analysis. Limits: 5,000 points, 300 km, 1 MB."
    },
    "elevation": {
      "type": "string",
      "enum": [
        "auto",
        "recorded",
        "terrain"
      ],
      "default": "auto"
    },
    "points": {
      "type": "integer",
      "minimum": 2,
      "maximum": 6000,
      "default": 1000,
      "description": "At most this many points in the series."
    }
  },
  "additionalProperties": true
}

Schema references resolve in the downloadable OpenAPI file. A shape check does not establish field accuracy or physical route suitability.

POST

Route through waypoints

/v1/route

A walking, running or cycling route through 2 to 100 waypoints, on signed trails by default. Returns the route as a GeoJSON line with its legs and the same facts as round trips and route analysis: climb, the hike time with its scope, surfaces, ways, SAC grades, fords and aided passages, turn-by-turn steps and every unknown. The same router as the Valhalla-compatible POST /route/v1, in the /v1 style: [lon, lat] waypoints, flat snake_case settings, errors as { error: { code, message } }. Credits as /route/v1: 1, plus 1 per further 10 waypoints.

Full reference, examples in curl, JavaScript and Python, and Try it →

Inspect request and response shapes
Route through waypoints request
curl --fail-with-body 'https://api.trailsplits.com/v1/route' \
  -H 'Content-Type: application/json' \
  --data '{"waypoints":[[7.7475,46.0207],[7.7174,46.0091],[7.7355,46.0036]]}'

Route through waypoints contract
{
  "post": {
    "operationId": "waypoint-route",
    "summary": "Route through waypoints",
    "description": "A walking, running or cycling route through 2 to 100 waypoints, on signed trails by default. Returns the route as a GeoJSON line with its legs and the same facts as round trips and route analysis: climb, the hike time with its scope, surfaces, ways, SAC grades, fords and aided passages, turn-by-turn steps and every unknown. The same router as the Valhalla-compatible POST /route/v1, in the /v1 style: [lon, lat] waypoints, flat snake_case settings, errors as { error: { code, message } }. Credits as /route/v1: 1, plus 1 per further 10 waypoints.",
    "tags": [
      "Developer preview"
    ],
    "security": [
      {},
      {
        "ApiKey": []
      }
    ],
    "parameters": [],
    "requestBody": {
      "required": true,
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/WaypointRouteInput"
          }
        }
      }
    },
    "responses": {
      "200": {
        "description": "Successful response; additive fields are allowed.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/WaypointRoute"
            }
          }
        }
      },
      "400": {
        "description": "Documented error/refusal; no result geometry should be fabricated.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ProductError"
            }
          }
        }
      },
      "413": {
        "description": "Documented error/refusal; no result geometry should be fabricated.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ProductError"
            }
          }
        }
      },
      "422": {
        "description": "Documented error/refusal; no result geometry should be fabricated.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ProductError"
            }
          }
        }
      },
      "503": {
        "description": "Documented error/refusal; no result geometry should be fabricated.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ProductError"
            }
          }
        }
      },
      "default": {
        "description": "Other gateway/provider failures are possible in preview. Consumers bound and surface them; do not treat an unknown status as success."
      }
    }
  }
}

Route through waypoints response fields
{
  "type": "object",
  "properties": {
    "schema": {
      "type": "string",
      "enum": [
        "route/1"
      ]
    },
    "engine": {
      "type": "object",
      "additionalProperties": true
    },
    "status": {
      "type": "string",
      "enum": [
        "complete",
        "best_effort"
      ],
      "description": "complete: every leg is a proven cheapest path under the settings. best_effort: a leg hit the search budget (a warning says which)."
    },
    "settings": {
      "type": "object",
      "additionalProperties": true,
      "description": "What was applied, in the request’s words."
    },
    "settings_defaulted": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "distance_m": {
      "type": "number"
    },
    "ascent_m": {
      "type": "number"
    },
    "descent_m": {
      "type": "number"
    },
    "ascent_method": {
      "type": "string"
    },
    "time": {
      "type": "object",
      "nullable": true,
      "additionalProperties": true,
      "description": "Hike only: moving time from the calibrated trailsplits-hike/2 model, with its scope and error; region (the main country, its share, every country crossed with its calibration_legs) and notes. A country with no published times in the calibration puts the time outside_calibration. Null for run and bike."
    },
    "surfaces": {
      "type": "object",
      "additionalProperties": true,
      "description": "Paved, gravel, trail and unknown metres; mapped or assumed from the kind of way; stretches placed along the route."
    },
    "hazards": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "kind": {
            "type": "string",
            "enum": [
              "ford",
              "aid",
              "via_ferrata"
            ]
          },
          "from_m": {
            "type": "number"
          },
          "to_m": {
            "type": "number"
          },
          "length_m": {
            "type": "number"
          },
          "way_id": {
            "type": "number",
            "nullable": true
          }
        },
        "required": [
          "kind",
          "from_m",
          "to_m",
          "length_m",
          "way_id"
        ],
        "additionalProperties": true
      }
    },
    "ways": {
      "type": "object",
      "additionalProperties": true
    },
    "difficulty": {
      "type": "object",
      "nullable": true,
      "additionalProperties": true,
      "description": "SAC-tagged metres by grade, untagged path and road metres, and the hardest stretch."
    },
    "warnings": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "code": {
            "type": "string"
          },
          "message": {
            "type": "string"
          },
          "location": {
            "type": "array",
            "items": {
              "type": "number"
            },
            "nullable": true
          }
        },
        "required": [
          "code",
          "message",
          "location"
        ],
        "additionalProperties": true
      }
    },
    "unknowns": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "code": {
            "type": "string"
          },
          "message": {
            "type": "string"
          }
        },
        "required": [
          "code",
          "message"
        ],
        "additionalProperties": true
      }
    },
    "geometry": {
      "type": "object",
      "properties": {
        "type": {
          "type": "string",
          "enum": [
            "LineString"
          ]
        },
        "coordinates": {
          "type": "array",
          "minItems": 2,
          "items": {
            "type": "array",
            "items": {
              "type": "number"
            }
          },
          "description": "[lon, lat, height]. The heights are the routing graph’s node heights, for drawing; ascent_m, the legs’ climb and the time come from terrain samples, so a climb summed from these heights (a GPX export opened elsewhere) will not reproduce ascent_m, by design."
        }
      },
      "required": [
        "type",
        "coordinates"
      ],
      "additionalProperties": true
    },
    "legs": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "leg": {
            "type": "integer"
          },
          "distance_m": {
            "type": "number"
          },
          "ascent_m": {
            "type": "number"
          },
          "descent_m": {
            "type": "number"
          },
          "from_snap_m": {
            "type": "number"
          },
          "to_snap_m": {
            "type": "number"
          }
        },
        "required": [
          "leg",
          "distance_m",
          "ascent_m",
          "descent_m",
          "from_snap_m",
          "to_snap_m"
        ],
        "additionalProperties": true
      }
    },
    "snaps": {
      "type": "array",
      "items": {
        "type": "object",
        "additionalProperties": true
      }
    },
    "maneuvers": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "instruction": {
            "type": "string"
          },
          "type": {
            "type": "string"
          },
          "location": {
            "type": "array",
            "items": {
              "type": "number"
            }
          },
          "distance_m": {
            "type": "number"
          }
        },
        "required": [
          "instruction",
          "type",
          "location",
          "distance_m"
        ],
        "additionalProperties": true
      }
    },
    "cap_alternative": {
      "type": "object",
      "nullable": true,
      "additionalProperties": true,
      "description": "When the grade cap was left at its default and a harder path is much shorter: its max_sac, distance, climb and minutes."
    }
  },
  "required": [
    "schema",
    "engine",
    "status",
    "settings",
    "distance_m",
    "ascent_m",
    "descent_m",
    "time",
    "surfaces",
    "hazards",
    "warnings",
    "unknowns",
    "geometry",
    "legs",
    "maneuvers"
  ],
  "additionalProperties": true
}

Route through waypoints request fields
{
  "type": "object",
  "properties": {
    "waypoints": {
      "type": "array",
      "minItems": 2,
      "maxItems": 100,
      "items": {
        "type": "array",
        "minItems": 2,
        "maxItems": 2,
        "items": {
          "type": "number"
        }
      },
      "description": "2 to 100 points, [lon, lat]. A leg (between two waypoints) may be at most 60 km in a straight line."
    },
    "profile": {
      "type": "string",
      "enum": [
        "hike",
        "run",
        "bike"
      ],
      "default": "hike"
    },
    "max_sac": {
      "type": "integer",
      "minimum": 1,
      "maximum": 6,
      "default": 3,
      "description": "Hike and run: the hardest SAC grade allowed, 1 (T1) to 6 (T6). Refused for a bike."
    },
    "marked_trails": {
      "type": "string",
      "enum": [
        "strict",
        "prefer",
        "off"
      ],
      "default": "prefer",
      "description": "Hike and run: how strongly to keep to waymarked trails. Refused for a bike."
    },
    "avoid_paved": {
      "type": "boolean",
      "default": false
    },
    "hills": {
      "type": "number",
      "minimum": -1,
      "maximum": 1,
      "default": 0,
      "description": "From -1 (avoid climbing) to 1 (seek it)."
    },
    "shortest": {
      "type": "boolean",
      "default": false,
      "description": "The shortest route under the other settings, not the most suitable."
    },
    "bicycle_type": {
      "type": "string",
      "enum": [
        "road",
        "hybrid",
        "mountain"
      ],
      "description": "Bike only."
    },
    "straight_legs": {
      "type": "array",
      "items": {
        "type": "integer"
      },
      "description": "Leg numbers, counted from 0 (leg 0 joins waypoint 0 to waypoint 1), to draw straight, on no mapped path."
    },
    "snap_radius_m": {
      "type": "number",
      "minimum": 10,
      "maximum": 5000,
      "description": "How far a waypoint may lie from a usable path."
    }
  },
  "required": [
    "waypoints"
  ],
  "additionalProperties": true
}

Schema references resolve in the downloadable OpenAPI file. A shape check does not establish field accuracy or physical route suitability.

POST

Exits along a route

/v1/route-exits

Where can I get off this? Along one day’s line: the nearest mapped public road, public-transport stop, village and hut every kilometre, each with its walking time (Swiss signpost method, on mapped paths a walker may use, at your pace_factor) and distance, placed in metres along the line; plus the longest stretch with no road, stop or village within an hour’s walk. A mapped way out, never a safe one: a road may be closed, a stop keeps a timetable (lifts and pass buses can be seasonal, and a station can sit inside a mountain), and a hut is shelter, not a way out. 5 credits; heavy.

Full reference, examples in curl, JavaScript and Python, and Try it →

Inspect request and response shapes
Exits along a route request
curl --fail-with-body 'https://api.trailsplits.com/v1/route-exits' \
  -H 'Content-Type: application/json' \
  --data '{"geometry":{"type":"LineString","coordinates":[[6.97178,45.79266],[6.98409,45.80185],[6.98629,45.80488],[6.98231,45.80634],[6.9782,45.80782],[6.9784,45.81286],[6.98961,45.82424],[7.00303,45.82901],[7.0139,45.83525],[7.02084,45.83669],[7.02859,45.84621],[7.03402,45.84664]]}}'

Exits along a route contract
{
  "post": {
    "operationId": "route-exits",
    "summary": "Exits along a route",
    "description": "Where can I get off this? Along one day’s line: the nearest mapped public road, public-transport stop, village and hut every kilometre, each with its walking time (Swiss signpost method, on mapped paths a walker may use, at your pace_factor) and distance, placed in metres along the line; plus the longest stretch with no road, stop or village within an hour’s walk. A mapped way out, never a safe one: a road may be closed, a stop keeps a timetable (lifts and pass buses can be seasonal, and a station can sit inside a mountain), and a hut is shelter, not a way out. 5 credits; heavy.",
    "tags": [
      "Developer preview"
    ],
    "security": [
      {},
      {
        "ApiKey": []
      }
    ],
    "parameters": [],
    "requestBody": {
      "required": true,
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/RouteExitsInput"
          }
        }
      }
    },
    "responses": {
      "200": {
        "description": "Successful response; additive fields are allowed.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/RouteExits"
            }
          }
        }
      },
      "400": {
        "description": "Documented error/refusal; no result geometry should be fabricated.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ProductError"
            }
          }
        }
      },
      "413": {
        "description": "Documented error/refusal; no result geometry should be fabricated.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ProductError"
            }
          }
        }
      },
      "422": {
        "description": "Documented error/refusal; no result geometry should be fabricated.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ProductError"
            }
          }
        }
      },
      "503": {
        "description": "Documented error/refusal; no result geometry should be fabricated.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ProductError"
            }
          }
        }
      },
      "default": {
        "description": "Other gateway/provider failures are possible in preview. Consumers bound and surface them; do not treat an unknown status as success."
      }
    }
  }
}

Exits along a route response fields
{
  "type": "object",
  "properties": {
    "schema": {
      "type": "string",
      "enum": [
        "route-exits/1"
      ]
    },
    "engine": {
      "type": "object",
      "additionalProperties": true
    },
    "settings": {
      "type": "object",
      "additionalProperties": true,
      "description": "pace_factor, within_minutes (60), sample_every_m, along_every_m."
    },
    "settings_defaulted": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "input": {
      "type": "object",
      "properties": {
        "format": {
          "type": "string"
        },
        "points": {
          "type": "integer"
        },
        "length_m": {
          "type": "number"
        }
      },
      "required": [
        "length_m"
      ],
      "additionalProperties": true
    },
    "method": {
      "type": "object",
      "additionalProperties": true
    },
    "along": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "at_m": {
            "type": "number"
          },
          "road": {
            "type": "object",
            "nullable": true,
            "additionalProperties": true,
            "description": "{ exit, minutes, walk_m } for the nearest within the hour, or null."
          },
          "transport": {
            "type": "object",
            "nullable": true,
            "additionalProperties": true
          },
          "settlement": {
            "type": "object",
            "nullable": true,
            "additionalProperties": true
          },
          "hut": {
            "type": "object",
            "nullable": true,
            "additionalProperties": true,
            "description": "Shelter, not a way out: never ends a stretch."
          }
        },
        "required": [
          "at_m"
        ],
        "additionalProperties": true
      }
    },
    "exits": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "kind": {
            "type": "string",
            "enum": [
              "road",
              "transport",
              "settlement",
              "hut"
            ]
          },
          "place_kind": {
            "type": "string"
          },
          "name": {
            "type": "string",
            "nullable": true
          },
          "lon": {
            "type": "number"
          },
          "lat": {
            "type": "number"
          },
          "osm_id": {
            "type": "string"
          }
        },
        "required": [
          "id",
          "kind",
          "lon",
          "lat"
        ],
        "additionalProperties": true
      }
    },
    "longest_without_exit": {
      "type": "object",
      "properties": {
        "within_minutes": {
          "type": "number"
        },
        "kinds": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "stretch": {
          "type": "object",
          "nullable": true,
          "additionalProperties": true,
          "description": "from_m, to_m, length_m of the longest stretch with no road, stop or village within the hour, or null."
        }
      },
      "required": [
        "within_minutes",
        "stretch"
      ],
      "additionalProperties": true
    },
    "longest_without": {
      "type": "object",
      "additionalProperties": true,
      "description": "The same stretch per kind."
    },
    "note": {
      "type": "string"
    },
    "unknowns": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "code": {
            "type": "string"
          },
          "message": {
            "type": "string"
          }
        },
        "required": [
          "code",
          "message"
        ],
        "additionalProperties": true
      }
    }
  },
  "required": [
    "schema",
    "engine",
    "input",
    "along",
    "exits",
    "longest_without_exit",
    "unknowns"
  ],
  "additionalProperties": true
}

Exits along a route request fields
{
  "type": "object",
  "properties": {
    "gpx": {
      "type": "string",
      "description": "One line as GPX, one part, at most 120 km and 5,000 points. Or geometry, not both."
    },
    "geometry": {
      "type": "object",
      "additionalProperties": true,
      "description": "A GeoJSON LineString, [lon, lat]."
    },
    "pace_factor": {
      "type": "number",
      "minimum": 0.5,
      "maximum": 2,
      "default": 1,
      "description": "Scales the signpost walking times (1.25 = 25 % slower)."
    }
  },
  "additionalProperties": true
}

Schema references resolve in the downloadable OpenAPI file. A shape check does not establish field accuracy or physical route suitability.

POST

Day outings near a point

/v1/outings

Where can I walk near here? An ordered list of day outings near a point: TrailSplits’ curated outings (Switzerland and its borders so far) and, when they do not fill the list, round trips built from your point anywhere the map covers. Each outing carries its facts (length, climb, moving time, hardest tagged grade, stops at the ends, mapped water) and the sentences saying why it is listed; with a date, its go window for that day. Every rule you set leaves out what it cannot judge, counted in left_out: unknown never passes as easy. Facts, not a rating: closures, snow and fires are not assessed. 10 credits; heavy.

Full reference, examples in curl, JavaScript and Python, and Try it →

Inspect request and response shapes
Day outings near a point request
curl --fail-with-body 'https://api.trailsplits.com/v1/outings' \
  -H 'Content-Type: application/json' \
  --data '{"lat":46.6863,"lon":7.8632,"radius_km":20,"max_hours":4,"max_grade":"T2","car_free":true}'

Day outings near a point contract
{
  "post": {
    "operationId": "outings",
    "summary": "Day outings near a point",
    "description": "Where can I walk near here? An ordered list of day outings near a point: TrailSplits’ curated outings (Switzerland and its borders so far) and, when they do not fill the list, round trips built from your point anywhere the map covers. Each outing carries its facts (length, climb, moving time, hardest tagged grade, stops at the ends, mapped water) and the sentences saying why it is listed; with a date, its go window for that day. Every rule you set leaves out what it cannot judge, counted in left_out: unknown never passes as easy. Facts, not a rating: closures, snow and fires are not assessed. 10 credits; heavy.",
    "tags": [
      "Developer preview"
    ],
    "security": [
      {},
      {
        "ApiKey": []
      }
    ],
    "parameters": [],
    "requestBody": {
      "required": true,
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/OutingsInput"
          }
        }
      }
    },
    "responses": {
      "200": {
        "description": "Successful response; additive fields are allowed.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Outings"
            }
          }
        }
      },
      "400": {
        "description": "Documented error/refusal; no result geometry should be fabricated.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ProductError"
            }
          }
        }
      },
      "422": {
        "description": "Documented error/refusal; no result geometry should be fabricated.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ProductError"
            }
          }
        }
      },
      "503": {
        "description": "Documented error/refusal; no result geometry should be fabricated.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ProductError"
            }
          }
        }
      },
      "default": {
        "description": "Other gateway/provider failures are possible in preview. Consumers bound and surface them; do not treat an unknown status as success."
      }
    }
  }
}

Day outings near a point response fields
{
  "type": "object",
  "properties": {
    "schema": {
      "type": "string",
      "enum": [
        "outings/1"
      ]
    },
    "engine": {
      "type": "object",
      "additionalProperties": true
    },
    "request": {
      "type": "object",
      "additionalProperties": true
    },
    "settings_defaulted": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "ordered_by": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "outings": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "rank": {
            "type": "integer"
          },
          "id": {
            "type": "string"
          },
          "source": {
            "type": "string",
            "enum": [
              "curated",
              "generated"
            ]
          },
          "kind": {
            "type": "string"
          },
          "name": {
            "type": "string",
            "nullable": true
          },
          "url": {
            "type": "string",
            "nullable": true
          },
          "shape": {
            "type": "string",
            "enum": [
              "loop",
              "a_to_b"
            ]
          },
          "start": {
            "type": "object",
            "additionalProperties": true
          },
          "finish": {
            "type": "object",
            "additionalProperties": true
          },
          "length_m": {
            "type": "number"
          },
          "ascent_m": {
            "type": "number",
            "nullable": true,
            "description": "null when not known, never 0."
          },
          "moving_minutes": {
            "type": "number",
            "nullable": true
          },
          "time_basis": {
            "type": "string",
            "nullable": true
          },
          "hardest_grade": {
            "type": "string",
            "nullable": true
          },
          "window": {
            "type": "object",
            "nullable": true,
            "additionalProperties": true
          },
          "notices": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "code": {
                  "type": "string"
                },
                "message": {
                  "type": "string"
                }
              },
              "required": [
                "code",
                "message"
              ],
              "additionalProperties": true
            }
          },
          "why": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "line": {
            "type": "string",
            "description": "Encoded polyline (precision 6), at most 160 points: send it as geometry to the route brief or route card."
          }
        },
        "required": [
          "rank",
          "id",
          "source",
          "shape",
          "length_m",
          "why",
          "line"
        ],
        "additionalProperties": true
      }
    },
    "matched": {
      "type": "integer"
    },
    "left_out": {
      "type": "object",
      "additionalProperties": {
        "type": "integer"
      },
      "description": "Per rule, how many outings it left out (farther, shape, longer, slower, time_unknown, more_climb, harder, grade_unknown, no_stop_at_start, water_gap, water_unknown)."
    },
    "generated": {
      "type": "object",
      "nullable": true,
      "additionalProperties": true
    },
    "index": {
      "type": "object",
      "additionalProperties": true
    },
    "note": {
      "type": "string"
    },
    "unknowns": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "code": {
            "type": "string"
          },
          "message": {
            "type": "string"
          }
        },
        "required": [
          "code",
          "message"
        ],
        "additionalProperties": true
      }
    }
  },
  "required": [
    "schema",
    "engine",
    "request",
    "outings",
    "matched",
    "left_out",
    "unknowns"
  ],
  "additionalProperties": true
}

Day outings near a point request fields
{
  "type": "object",
  "properties": {
    "lat": {
      "type": "number",
      "minimum": -90,
      "maximum": 90
    },
    "lon": {
      "type": "number",
      "minimum": -180,
      "maximum": 180
    },
    "radius_km": {
      "type": "number",
      "minimum": 1,
      "maximum": 100,
      "default": 25
    },
    "date": {
      "type": "string",
      "description": "YYYY-MM-DD, local time at the outings, from today up to 7 days ahead: adds each outing’s go window and orders the list by it."
    },
    "start_time": {
      "type": "string",
      "description": "Local HH:MM on date (09:00). Only with a date."
    },
    "activity": {
      "type": "string",
      "enum": [
        "hike",
        "run"
      ],
      "default": "hike"
    },
    "pace_factor": {
      "description": "Hike only: relaxed (1.25), usual (1), brisk (0.85), or 0.5 to 2."
    },
    "min_per_km": {
      "type": "number",
      "minimum": 2,
      "maximum": 20,
      "description": "Run only; needed with max_hours or a date."
    },
    "max_hours": {
      "type": "number",
      "minimum": 0.5,
      "maximum": 12
    },
    "max_km": {
      "type": "number",
      "minimum": 1,
      "maximum": 40
    },
    "max_ascent_m": {
      "type": "number",
      "minimum": 50,
      "maximum": 5000
    },
    "max_grade": {
      "type": "string",
      "enum": [
        "T1",
        "T2",
        "T3",
        "T4",
        "T5",
        "T6"
      ],
      "description": "SAC scale. A line it cannot judge (untagged or off mapped paths) is left out, never passed as easy."
    },
    "shape": {
      "type": "string",
      "enum": [
        "loop",
        "a_to_b",
        "any"
      ],
      "default": "any"
    },
    "car_free": {
      "type": "boolean",
      "default": false,
      "description": "A mapped public-transport stop within 500 m of the start."
    },
    "water": {
      "type": "boolean",
      "default": false,
      "description": "Mapped drinking water at least every 8 km."
    },
    "generate": {
      "type": "boolean",
      "default": true,
      "description": "false: curated outings only."
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 10,
      "default": 5
    }
  },
  "required": [
    "lat",
    "lon"
  ],
  "additionalProperties": true
}

Schema references resolve in the downloadable OpenAPI file. A shape check does not establish field accuracy or physical route suitability.

POST

Your own walking pace (time model)

/v1/time-model/fit

Send 1 to 30 of a person’s own timed walks. You get their pace against the TrailSplits hike time model on level ground, uphill and downhill, each with its uncertainty, as pace_profile. Pass it to route analysis, the route brief, route weather or go windows for that person’s own time beside the model’s. Nothing is kept: the walks are read, fitted and dropped, and the answer has no coordinates or times. A profile names its base_version; after a refit of the model it is refused (422 pace_profile_stale): fit again. 5 credits; at most 2 at a time per project.

Full reference, examples in curl, JavaScript and Python, and Try it →

Inspect request and response shapes
Your own walking pace (time model) request
# walks.json: {"activities": [{"gpx": "<gpx>…</gpx>"}, …]}, 1 to 30 of your own timed walks (nothing is stored).
curl --fail-with-body 'https://api.trailsplits.com/v1/time-model/fit' \
  -H 'Content-Type: application/json' \
  --data @walks.json

Your own walking pace (time model) contract
{
  "post": {
    "operationId": "time-model-fit",
    "summary": "Your own walking pace (time model)",
    "description": "Send 1 to 30 of a person’s own timed walks. You get their pace against the TrailSplits hike time model on level ground, uphill and downhill, each with its uncertainty, as pace_profile. Pass it to route analysis, the route brief, route weather or go windows for that person’s own time beside the model’s. Nothing is kept: the walks are read, fitted and dropped, and the answer has no coordinates or times. A profile names its base_version; after a refit of the model it is refused (422 pace_profile_stale): fit again. 5 credits; at most 2 at a time per project.",
    "tags": [
      "Developer preview"
    ],
    "security": [
      {},
      {
        "ApiKey": []
      }
    ],
    "parameters": [],
    "requestBody": {
      "required": true,
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/TimeModelFitInput"
          }
        }
      }
    },
    "responses": {
      "200": {
        "description": "Successful response; additive fields are allowed.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/TimeModelFit"
            }
          }
        }
      },
      "400": {
        "description": "Documented error/refusal; no result geometry should be fabricated.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ProductError"
            }
          }
        }
      },
      "413": {
        "description": "Documented error/refusal; no result geometry should be fabricated.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ProductError"
            }
          }
        }
      },
      "422": {
        "description": "Documented error/refusal; no result geometry should be fabricated.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ProductError"
            }
          }
        }
      },
      "503": {
        "description": "Documented error/refusal; no result geometry should be fabricated.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ProductError"
            }
          }
        }
      },
      "default": {
        "description": "Other gateway/provider failures are possible in preview. Consumers bound and surface them; do not treat an unknown status as success."
      }
    }
  }
}

Your own walking pace (time model) response fields
{
  "type": "object",
  "properties": {
    "schema": {
      "type": "string",
      "enum": [
        "time-model/1"
      ]
    },
    "engine": {
      "type": "object",
      "additionalProperties": true
    },
    "base_model": {
      "type": "string",
      "enum": [
        "trailsplits-hike/2"
      ]
    },
    "base_version": {
      "type": "string"
    },
    "pace_profile": {
      "type": "object",
      "properties": {
        "base_model": {
          "type": "string"
        },
        "base_version": {
          "type": "string"
        },
        "factors": {
          "type": "object",
          "properties": {
            "level": {
              "type": "number"
            },
            "up": {
              "type": "number"
            },
            "down": {
              "type": "number"
            }
          },
          "required": [
            "level",
            "up",
            "down"
          ],
          "additionalProperties": true
        },
        "log_sd": {
          "type": "object",
          "properties": {
            "level": {
              "type": "number"
            },
            "up": {
              "type": "number"
            },
            "down": {
              "type": "number"
            }
          },
          "required": [
            "level",
            "up",
            "down"
          ],
          "additionalProperties": true
        },
        "day_log_sd": {
          "type": "number"
        },
        "activities": {
          "type": "integer"
        }
      },
      "required": [
        "base_version",
        "factors",
        "log_sd",
        "day_log_sd"
      ],
      "additionalProperties": true
    },
    "by_class": {
      "type": "object",
      "additionalProperties": true
    },
    "activities": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "index": {
            "type": "integer"
          },
          "used": {
            "type": "boolean"
          },
          "reason": {
            "type": "string",
            "nullable": true
          },
          "length_m": {
            "type": "number"
          },
          "moving_minutes": {
            "type": "number"
          },
          "stopped_minutes": {
            "type": "number"
          },
          "model_minutes": {
            "type": "number"
          }
        },
        "required": [
          "index",
          "used"
        ],
        "additionalProperties": true
      }
    },
    "method": {
      "type": "object",
      "additionalProperties": true
    },
    "note": {
      "type": "string"
    },
    "unknowns": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "code": {
            "type": "string"
          },
          "message": {
            "type": "string"
          }
        },
        "required": [
          "code",
          "message"
        ],
        "additionalProperties": true
      }
    }
  },
  "required": [
    "schema",
    "base_version",
    "pace_profile",
    "by_class",
    "activities",
    "unknowns"
  ],
  "additionalProperties": true
}

Your own walking pace (time model) request fields
{
  "type": "object",
  "properties": {
    "activities": {
      "type": "array",
      "minItems": 1,
      "maxItems": 30,
      "items": {
        "type": "object",
        "additionalProperties": true,
        "description": "{ gpx } with <time> on its track points, or { points: [[lon, lat, time], …] } (time ISO 8601 or epoch seconds). At most 20,000 points each, 15 MB in all. A person’s own walks; nothing is stored."
      }
    }
  },
  "required": [
    "activities"
  ],
  "additionalProperties": true
}

Schema references resolve in the downloadable OpenAPI file. A shape check does not establish field accuracy or physical route suitability.

POST

Route card to print

/v1/route-card

A card to print and keep for a line you send, as one self-contained HTML page (works offline, no scripts) or a PDF on A4 or Letter: the map, the elevation profile, legs between your waypoints with distance, climb and moving time, water and huts along the line, weather and sun only when you give a date (models named), a cue sheet if you send one, the sources, and a QR code to the trailsplits.com link you give. Nothing is stored or published, and it carries no identity. Climb is "not measured" without heights and "≈" for a terrain estimate; times are your own (leg_seconds) or the hike model’s. 10 credits.

Full reference, examples in curl, JavaScript and Python, and Try it →

Inspect request and response shapes
Route card to print request
curl --fail-with-body 'https://api.trailsplits.com/v1/route-card' \
  -H 'Content-Type: application/json' \
  --data '{"geometry":{"type":"LineString","coordinates":[[6.97178,45.79266],[6.98409,45.80185],[6.98629,45.80488],[6.98231,45.80634],[6.9782,45.80782],[6.9784,45.81286],[6.98961,45.82424],[7.00303,45.82901],[7.0139,45.83525],[7.02084,45.83669],[7.02859,45.84621],[7.03402,45.84664]]},"name":"Courmayeur – Rifugio Bonatti","waypoints":[{"lon":6.971776,"lat":45.792663,"name":"Courmayeur"},{"lon":6.979459,"lat":45.817503,"name":"Midway"},{"lon":7.034022,"lat":45.846641,"name":"Rifugio Bonatti"}],"link":"https://trailsplits.com/planner"}' \
  -o card.html

Route card to print contract
{
  "post": {
    "operationId": "route-card",
    "summary": "Route card to print",
    "description": "A card to print and keep for a line you send, as one self-contained HTML page (works offline, no scripts) or a PDF on A4 or Letter: the map, the elevation profile, legs between your waypoints with distance, climb and moving time, water and huts along the line, weather and sun only when you give a date (models named), a cue sheet if you send one, the sources, and a QR code to the trailsplits.com link you give. Nothing is stored or published, and it carries no identity. Climb is \"not measured\" without heights and \"≈\" for a terrain estimate; times are your own (leg_seconds) or the hike model’s. 10 credits.",
    "tags": [
      "Developer preview"
    ],
    "security": [
      {},
      {
        "ApiKey": []
      }
    ],
    "parameters": [],
    "requestBody": {
      "required": true,
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/RouteCardInput"
          }
        }
      }
    },
    "responses": {
      "200": {
        "description": "text/html (format html) or application/pdf (format pdf)",
        "content": {
          "text/html": {
            "schema": {
              "type": "string"
            }
          },
          "application/pdf": {
            "schema": {
              "type": "string",
              "format": "binary"
            }
          }
        }
      },
      "400": {
        "description": "Documented error/refusal; no result geometry should be fabricated.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ProductError"
            }
          }
        }
      },
      "413": {
        "description": "Documented error/refusal; no result geometry should be fabricated.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ProductError"
            }
          }
        }
      },
      "422": {
        "description": "Documented error/refusal; no result geometry should be fabricated.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ProductError"
            }
          }
        }
      },
      "503": {
        "description": "Documented error/refusal; no result geometry should be fabricated.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ProductError"
            }
          }
        }
      },
      "default": {
        "description": "Other gateway/provider failures are possible in preview. Consumers bound and surface them; do not treat an unknown status as success."
      }
    }
  }
}

Route card to print request fields
{
  "type": "object",
  "properties": {
    "gpx": {
      "type": "string",
      "description": "The line as GPX (parts kept, no line drawn across a gap). Or geometry, not both. Limits: 5,000 points, 300 km."
    },
    "geometry": {
      "type": "object",
      "additionalProperties": true,
      "description": "A GeoJSON LineString or MultiLineString, [lon, lat]."
    },
    "name": {
      "type": "string",
      "maxLength": 120,
      "default": "Route card",
      "description": "The card’s title."
    },
    "waypoints": {
      "type": "array",
      "maxItems": 60,
      "items": {
        "type": "object",
        "properties": {
          "lon": {
            "type": "number"
          },
          "lat": {
            "type": "number"
          },
          "name": {
            "type": "string"
          }
        },
        "required": [
          "lon",
          "lat"
        ],
        "additionalProperties": true
      },
      "description": "Start and finish included; placed on the line forward only. Legs run between them."
    },
    "leg_seconds": {
      "type": "array",
      "items": {
        "type": "number"
      },
      "description": "Your own moving seconds per leg, so the card matches your screen; one per leg."
    },
    "pace_factor": {
      "description": "relaxed, usual, brisk, or a number from 0.5 to 2; used without leg_seconds."
    },
    "profile": {
      "type": "string",
      "enum": [
        "hike",
        "run",
        "bike"
      ],
      "default": "hike"
    },
    "cues": {
      "type": "array",
      "maxItems": 400,
      "items": {
        "type": "object",
        "properties": {
          "at_m": {
            "type": "number"
          },
          "text": {
            "type": "string"
          }
        },
        "required": [
          "at_m",
          "text"
        ],
        "additionalProperties": true
      },
      "description": "For the cue sheet."
    },
    "units": {
      "type": "string",
      "enum": [
        "metric",
        "imperial"
      ],
      "default": "metric"
    },
    "paper": {
      "type": "string",
      "enum": [
        "a4",
        "letter"
      ],
      "default": "a4"
    },
    "format": {
      "type": "string",
      "enum": [
        "html",
        "pdf"
      ],
      "default": "html"
    },
    "departure": {
      "type": "string",
      "description": "ISO time with offset, for a one-part line: adds the weather and sun at the hour each point is reached. Without it there is no weather section."
    },
    "link": {
      "type": "string",
      "description": "The QR code’s target: a https://trailsplits.com/ address of at most 300 characters. Without it, no QR code."
    }
  },
  "additionalProperties": true
}

Schema references resolve in the downloadable OpenAPI file. A shape check does not establish field accuracy or physical route suitability.

POST

Go windows: which day and start time

/v1/route-windows

For one day’s line, the next 1–7 days × start times, each window with its forecast facts at the hour you reach each point: wet points, thunderstorm signal and the lowest height it reaches, the lowest feels-like, gusts at the highs, daylight at the start and finish. Ordered by the preferences you give (no_thunder, dry, daylight, calm, warm, cool), each window saying why it sits where it does. An ordering of facts, never a safety score; the thunderstorm signal is the model’s codes or storm energy, not that a storm will happen; snow and closures are not in it. One forecast fetch for all windows. 3 credits.

Full reference, examples in curl, JavaScript and Python, and Try it →

Inspect request and response shapes
Go windows: which day and start time request
curl --fail-with-body 'https://api.trailsplits.com/v1/route-windows' \
  -H 'Content-Type: application/json' \
  --data '{"geometry":{"type":"LineString","coordinates":[[6.97178,45.79266],[6.98409,45.80185],[6.98629,45.80488],[6.98231,45.80634],[6.9782,45.80782],[6.9784,45.81286],[6.98961,45.82424],[7.00303,45.82901],[7.0139,45.83525],[7.02084,45.83669],[7.02859,45.84621],[7.03402,45.84664]]},"days":3,"prefer":["no_thunder","dry","daylight"]}'

Go windows: which day and start time contract
{
  "post": {
    "operationId": "route-windows",
    "summary": "Go windows: which day and start time",
    "description": "For one day’s line, the next 1–7 days × start times, each window with its forecast facts at the hour you reach each point: wet points, thunderstorm signal and the lowest height it reaches, the lowest feels-like, gusts at the highs, daylight at the start and finish. Ordered by the preferences you give (no_thunder, dry, daylight, calm, warm, cool), each window saying why it sits where it does. An ordering of facts, never a safety score; the thunderstorm signal is the model’s codes or storm energy, not that a storm will happen; snow and closures are not in it. One forecast fetch for all windows. 3 credits.",
    "tags": [
      "Developer preview"
    ],
    "security": [
      {},
      {
        "ApiKey": []
      }
    ],
    "parameters": [],
    "requestBody": {
      "required": true,
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/RouteWindowsInput"
          }
        }
      }
    },
    "responses": {
      "200": {
        "description": "Successful response; additive fields are allowed.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/RouteWindows"
            }
          }
        }
      },
      "400": {
        "description": "Documented error/refusal; no result geometry should be fabricated.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ProductError"
            }
          }
        }
      },
      "413": {
        "description": "Documented error/refusal; no result geometry should be fabricated.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ProductError"
            }
          }
        }
      },
      "422": {
        "description": "Documented error/refusal; no result geometry should be fabricated.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ProductError"
            }
          }
        }
      },
      "503": {
        "description": "Documented error/refusal; no result geometry should be fabricated.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ProductError"
            }
          }
        }
      },
      "default": {
        "description": "Other gateway/provider failures are possible in preview. Consumers bound and surface them; do not treat an unknown status as success."
      }
    }
  }
}

Go windows: which day and start time response fields
{
  "type": "object",
  "properties": {
    "schema": {
      "type": "string",
      "enum": [
        "route-windows/1"
      ]
    },
    "engine": {
      "type": "object",
      "additionalProperties": true
    },
    "settings": {
      "type": "object",
      "additionalProperties": true
    },
    "settings_defaulted": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "The request fields that were not given and took their defaults."
    },
    "moving_minutes": {
      "type": "number",
      "description": "Moving time for the line, stops included."
    },
    "line": {
      "type": "object",
      "additionalProperties": true,
      "description": "points, length_m, heights, terrain_release and samples of the line read."
    },
    "forecast": {
      "type": "object",
      "additionalProperties": true
    },
    "best": {
      "type": "object",
      "nullable": true,
      "additionalProperties": true,
      "description": "id, date_local and start_local of the first window, or null."
    },
    "windows": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "\"<date_local>T<start_local>\": stable, for watches and diffs."
          },
          "rank": {
            "type": "integer"
          },
          "date_local": {
            "type": "string"
          },
          "start_local": {
            "type": "string"
          },
          "departure": {
            "type": "string"
          },
          "finish_local": {
            "type": "string"
          },
          "complete": {
            "type": "boolean"
          },
          "wet": {
            "type": "object",
            "additionalProperties": true
          },
          "thunder": {
            "type": "object",
            "additionalProperties": true,
            "description": "Signal points (thunder codes 95–99 or CAPE ≥ 1,000 J/kg): the model’s signal, not that a storm will happen."
          },
          "feels_like_min_c": {
            "type": "number",
            "nullable": true
          },
          "temp_c": {
            "type": "array",
            "items": {
              "type": "number",
              "nullable": true
            }
          },
          "gust_max_at_highs_kmh": {
            "type": "number",
            "nullable": true
          },
          "daylight": {
            "type": "object",
            "additionalProperties": true
          },
          "why": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "One sentence per preference, in your order. Complete windows first; then each preference; ties go to the earlier window."
          }
        },
        "required": [
          "id",
          "rank",
          "date_local",
          "start_local",
          "complete",
          "why"
        ],
        "additionalProperties": true
      }
    },
    "skipped_past": {
      "type": "integer",
      "description": "Start times already gone today, left out."
    },
    "note": {
      "type": "string"
    },
    "unknowns": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "code": {
            "type": "string"
          },
          "message": {
            "type": "string"
          }
        },
        "required": [
          "code",
          "message"
        ],
        "additionalProperties": true
      }
    }
  },
  "required": [
    "schema",
    "engine",
    "settings",
    "best",
    "windows",
    "unknowns"
  ],
  "additionalProperties": true
}

Go windows: which day and start time request fields
{
  "type": "object",
  "properties": {
    "gpx": {
      "type": "string",
      "description": "One line as GPX, one part, at most 120 km and 5,000 points. Or geometry, not both."
    },
    "geometry": {
      "type": "object",
      "additionalProperties": true,
      "description": "A GeoJSON LineString, [lon, lat]."
    },
    "from_date": {
      "type": "string",
      "description": "YYYY-MM-DD in the route’s own time, today to 7 days ahead. Default today."
    },
    "days": {
      "type": "integer",
      "minimum": 1,
      "maximum": 7,
      "default": 3,
      "description": "How many days, counting from_date itself (today by default): 1 to 7, default 3."
    },
    "starts": {
      "type": "array",
      "maxItems": 24,
      "items": {
        "type": "string"
      },
      "description": "Local start times HH:MM. Default 06:00 to 10:00 hourly. Or give start_from, start_to and start_step_min instead."
    },
    "start_from": {
      "type": "string",
      "description": "First start time HH:MM, with start_to and start_step_min, instead of starts."
    },
    "start_to": {
      "type": "string",
      "description": "Last start time HH:MM."
    },
    "start_step_min": {
      "type": "integer",
      "minimum": 30,
      "maximum": 240,
      "default": 60,
      "description": "Minutes between start times."
    },
    "prefer": {
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "no_thunder",
          "dry",
          "daylight",
          "calm",
          "warm",
          "cool"
        ]
      },
      "description": "Your preferences in order; default no_thunder, dry, daylight, calm. Not both warm and cool. Windows equal on every preference go to the earlier one, so add calm (or warm, cool) to separate them."
    },
    "profile": {
      "type": "string",
      "enum": [
        "hike",
        "run",
        "bike"
      ],
      "default": "hike",
      "description": "hike uses the calibrated hike time; run and bike need min_per_km or kmh."
    },
    "pace_factor": {
      "type": "number",
      "minimum": 0.5,
      "maximum": 2,
      "description": "Hike only: scales the hike time (1.2 = 20 % slower)."
    },
    "min_per_km": {
      "type": "number",
      "description": "Run: your pace on the flat."
    },
    "kmh": {
      "type": "number",
      "description": "Bike: your speed on the flat."
    },
    "stops": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "at_km": {
            "type": "number"
          },
          "minutes": {
            "type": "number"
          }
        },
        "required": [
          "at_km",
          "minutes"
        ],
        "additionalProperties": true
      }
    },
    "pace_profile": {
      "type": "object",
      "additionalProperties": true,
      "description": "Hike only: the pace_profile /v1/time-model/fit answered, sent unchanged. Adds the person’s own time (with an 80 % range) beside the model’s; refused with 422 pace_profile_stale after a refit of the model."
    }
  },
  "additionalProperties": true
}

Schema references resolve in the downloadable OpenAPI file. A shape check does not establish field accuracy or physical route suitability.

POST

Slope at the path (experimental)

/v1/route-slopes

Experimental. The stretches of a line where the terrain model at the path is 30° or steeper, in three classes (30–35°, 35–40°, 40° or more), each with the way the slope faces, plus the distance assessed and unknown and links to the official avalanche bulletins whose areas the line touches. It is the slope at the path: not the path’s own gradient, not the slopes above or beside it, not avalanche terrain and not a risk. The terrain model is about 26 m (never 2 m). Unknown is an answer, never flat: terrain_not_float_first means the area’s terrain model is being rebuilt (until about 9 October 2026). Bulletins are links by coarse area, never readings. 2 credits.

Full reference, examples in curl, JavaScript and Python, and Try it →

Inspect request and response shapes
Slope at the path (experimental) request
curl --fail-with-body 'https://api.trailsplits.com/v1/route-slopes' \
  -H 'Content-Type: application/json' \
  --data '{"geometry":{"type":"LineString","coordinates":[[7.70897,45.99171],[7.70598,45.98992],[7.70144,45.98991],[7.69482,45.98835],[7.69172,45.98857],[7.68236,45.98436],[7.68161,45.98354],[7.6798,45.98287],[7.67891,45.98253],[7.6774,45.98226],[7.67624,45.9823],[7.67478,45.98162]]}}'

Slope at the path (experimental) contract
{
  "post": {
    "operationId": "route-slopes",
    "summary": "Slope at the path (experimental)",
    "description": "Experimental. The stretches of a line where the terrain model at the path is 30° or steeper, in three classes (30–35°, 35–40°, 40° or more), each with the way the slope faces, plus the distance assessed and unknown and links to the official avalanche bulletins whose areas the line touches. It is the slope at the path: not the path’s own gradient, not the slopes above or beside it, not avalanche terrain and not a risk. The terrain model is about 26 m (never 2 m). Unknown is an answer, never flat: terrain_not_float_first means the area’s terrain model is being rebuilt (until about 9 October 2026). Bulletins are links by coarse area, never readings. 2 credits.",
    "tags": [
      "Developer preview"
    ],
    "security": [
      {},
      {
        "ApiKey": []
      }
    ],
    "parameters": [],
    "requestBody": {
      "required": true,
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/RouteSlopesInput"
          }
        }
      }
    },
    "responses": {
      "200": {
        "description": "Successful response; additive fields are allowed.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/RouteSlopes"
            }
          }
        }
      },
      "400": {
        "description": "Documented error/refusal; no result geometry should be fabricated.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ProductError"
            }
          }
        }
      },
      "413": {
        "description": "Documented error/refusal; no result geometry should be fabricated.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ProductError"
            }
          }
        }
      },
      "422": {
        "description": "Documented error/refusal; no result geometry should be fabricated.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ProductError"
            }
          }
        }
      },
      "default": {
        "description": "Other gateway/provider failures are possible in preview. Consumers bound and surface them; do not treat an unknown status as success."
      }
    }
  }
}

Slope at the path (experimental) response fields
{
  "type": "object",
  "properties": {
    "schema": {
      "type": "string",
      "enum": [
        "route-slopes/1"
      ]
    },
    "experimental": {
      "type": "boolean"
    },
    "label": {
      "type": "string",
      "description": "\"slope at the path\""
    },
    "engine": {
      "type": "object",
      "additionalProperties": true
    },
    "input": {
      "type": "object",
      "properties": {
        "format": {
          "type": "string"
        },
        "parts": {
          "type": "integer"
        },
        "points": {
          "type": "integer"
        },
        "length_m": {
          "type": "number"
        },
        "gaps_m": {
          "type": "array",
          "items": {
            "type": "number"
          }
        }
      },
      "required": [
        "length_m"
      ],
      "additionalProperties": true
    },
    "method": {
      "type": "object",
      "additionalProperties": true,
      "description": "Horn’s 3 × 3 on the ~26 m terrain model, every 25 m, with the resolution at the line’s latitude."
    },
    "classes": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "enum": [
              "30_35",
              "35_40",
              "40_plus"
            ]
          },
          "from_deg": {
            "type": "number"
          },
          "to_deg": {
            "type": "number",
            "nullable": true
          }
        },
        "required": [
          "id",
          "from_deg"
        ],
        "additionalProperties": true
      }
    },
    "totals": {
      "type": "object",
      "properties": {
        "length_m": {
          "type": "number"
        },
        "assessed_m": {
          "type": "number"
        },
        "unknown_m": {
          "type": "number"
        },
        "from_30_m": {
          "type": "number"
        },
        "from_35_m": {
          "type": "number"
        },
        "from_40_m": {
          "type": "number"
        }
      },
      "required": [
        "length_m",
        "assessed_m",
        "unknown_m",
        "from_30_m",
        "from_35_m",
        "from_40_m"
      ],
      "additionalProperties": true
    },
    "spans": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "from_m": {
            "type": "number"
          },
          "to_m": {
            "type": "number"
          },
          "class": {
            "type": "string",
            "enum": [
              "30_35",
              "35_40",
              "40_plus"
            ]
          },
          "max_slope_deg": {
            "type": "number"
          },
          "aspect": {
            "type": "string"
          },
          "aspect_deg": {
            "type": "number"
          },
          "method": {
            "type": "string"
          },
          "source": {
            "type": "string"
          },
          "resolution_m": {
            "type": "number"
          }
        },
        "required": [
          "from_m",
          "to_m",
          "class",
          "max_slope_deg"
        ],
        "additionalProperties": true
      }
    },
    "runs_from_30": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "from_m": {
            "type": "number"
          },
          "to_m": {
            "type": "number"
          },
          "length_m": {
            "type": "number"
          },
          "max_slope_deg": {
            "type": "number"
          }
        },
        "required": [
          "from_m",
          "to_m",
          "length_m",
          "max_slope_deg"
        ],
        "additionalProperties": true
      }
    },
    "unknown_spans": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "from_m": {
            "type": "number"
          },
          "to_m": {
            "type": "number"
          },
          "reason": {
            "type": "string"
          }
        },
        "required": [
          "from_m",
          "to_m",
          "reason"
        ],
        "additionalProperties": true
      }
    },
    "bulletins": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "service": {
            "type": "string"
          },
          "area": {
            "type": "string"
          },
          "url": {
            "type": "string"
          }
        },
        "required": [
          "service",
          "area",
          "url"
        ],
        "additionalProperties": true
      }
    },
    "unknowns": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "code": {
            "type": "string"
          },
          "message": {
            "type": "string"
          }
        },
        "required": [
          "code",
          "message"
        ],
        "additionalProperties": true
      }
    }
  },
  "required": [
    "schema",
    "experimental",
    "label",
    "engine",
    "input",
    "classes",
    "totals",
    "spans",
    "runs_from_30",
    "unknown_spans",
    "bulletins",
    "unknowns"
  ],
  "additionalProperties": true
}

Slope at the path (experimental) request fields
{
  "type": "object",
  "properties": {
    "gpx": {
      "type": "string",
      "description": "One line as GPX (several parts allowed; distances skip the gaps). Or geometry, not both. Limits: 120 km, 5,000 points, 1 MB. There are no thresholds to set."
    },
    "geometry": {
      "type": "object",
      "additionalProperties": true,
      "description": "A GeoJSON LineString or MultiLineString, [lon, lat]."
    }
  },
  "additionalProperties": true
}

Schema references resolve in the downloadable OpenAPI file. A shape check does not establish field accuracy or physical route suitability.

POST

Route brief

/v1/route-brief

One call for one day’s line: route analysis, weather at arrival time, sun and shade, places along the route and snow evidence, picked with include, each the same answer its own endpoint gives. Satellite fire hotspots (NASA FIRMS) within 10 km in the last 48 hours come in by default: heat seen from space, not a fire perimeter. On top, notices are fact codes placed along the line (a ford, a stretch tagged T4, 7 km without drinking water, a thunderstorm in the model at the hour you get there, fire hotspots nearby), each with its part and source. Notices are facts, never advice, gear or a safety score; snow_observed is never "now". A part that fails is null with the reason in unknowns. Heavy request; 10 credits.

Full reference, examples in curl, JavaScript and Python, and Try it →

Inspect request and response shapes
Route brief request
curl --fail-with-body 'https://api.trailsplits.com/v1/route-brief' \
  -H 'Content-Type: application/json' \
  --data '{"geometry":{"type":"LineString","coordinates":[[6.97178,45.79266],[6.98409,45.80185],[6.98629,45.80488],[6.98231,45.80634],[6.9782,45.80782],[6.9784,45.81286],[6.98961,45.82424],[7.00303,45.82901],[7.0139,45.83525],[7.02084,45.83669],[7.02859,45.84621],[7.03402,45.84664]]},"include":["analysis","places"]}'

Route brief contract
{
  "post": {
    "operationId": "route-brief",
    "summary": "Route brief",
    "description": "One call for one day’s line: route analysis, weather at arrival time, sun and shade, places along the route and snow evidence, picked with include, each the same answer its own endpoint gives. Satellite fire hotspots (NASA FIRMS) within 10 km in the last 48 hours come in by default: heat seen from space, not a fire perimeter. On top, notices are fact codes placed along the line (a ford, a stretch tagged T4, 7 km without drinking water, a thunderstorm in the model at the hour you get there, fire hotspots nearby), each with its part and source. Notices are facts, never advice, gear or a safety score; snow_observed is never \"now\". A part that fails is null with the reason in unknowns. Heavy request; 10 credits.",
    "tags": [
      "Developer preview"
    ],
    "security": [
      {},
      {
        "ApiKey": []
      }
    ],
    "parameters": [],
    "requestBody": {
      "required": true,
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/RouteBriefInput"
          }
        }
      }
    },
    "responses": {
      "200": {
        "description": "Successful response; additive fields are allowed.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/RouteBrief"
            }
          }
        }
      },
      "400": {
        "description": "Documented error/refusal; no result geometry should be fabricated.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ProductError"
            }
          }
        }
      },
      "413": {
        "description": "Documented error/refusal; no result geometry should be fabricated.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ProductError"
            }
          }
        }
      },
      "422": {
        "description": "Documented error/refusal; no result geometry should be fabricated.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ProductError"
            }
          }
        }
      },
      "503": {
        "description": "Documented error/refusal; no result geometry should be fabricated.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ProductError"
            }
          }
        }
      },
      "default": {
        "description": "Other gateway/provider failures are possible in preview. Consumers bound and surface them; do not treat an unknown status as success."
      }
    }
  }
}

Route brief response fields
{
  "type": "object",
  "properties": {
    "schema": {
      "type": "string",
      "enum": [
        "route-brief/1"
      ]
    },
    "engine": {
      "type": "object",
      "additionalProperties": true
    },
    "include": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "settings_defaulted": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "line": {
      "type": "object",
      "properties": {
        "length_m": {
          "type": "number"
        },
        "points": {
          "type": "integer"
        }
      },
      "required": [
        "length_m",
        "points"
      ],
      "additionalProperties": true
    },
    "notices": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "code": {
            "type": "string",
            "description": "A fact code, such as ford, via_ferrata, difficulty_t4_or_harder, off_mapped_paths, no_drinking_water_km (replaced no_mapped_water_km on 3 October 2026), fire_hotspots_nearby, no_exit_within_hour, snow_observed, thunderstorm_forecast, storm_energy_cape, freezing_temperature, strong_gusts, beyond_civil_twilight. New codes may appear; ignore unknown ones."
          },
          "from_m": {
            "type": "number"
          },
          "to_m": {
            "type": "number"
          },
          "value": {
            "type": "number",
            "nullable": true
          },
          "unit": {
            "type": "string",
            "nullable": true
          },
          "rule": {
            "type": "string",
            "nullable": true
          },
          "part": {
            "type": "string"
          },
          "source": {
            "type": "string"
          },
          "message": {
            "type": "string"
          }
        },
        "required": [
          "code",
          "from_m",
          "to_m",
          "part",
          "source",
          "message"
        ],
        "additionalProperties": true
      }
    },
    "analysis": {
      "type": "object",
      "nullable": true,
      "additionalProperties": true,
      "description": "As POST /v1/route-analysis answers, or null (see unknowns)."
    },
    "weather": {
      "type": "object",
      "nullable": true,
      "additionalProperties": true,
      "description": "As POST /v1/route-weather answers (with sun when included), or null."
    },
    "places": {
      "type": "object",
      "nullable": true,
      "additionalProperties": true,
      "description": "As POST /v1/route-places answers, or null."
    },
    "snow": {
      "type": "object",
      "nullable": true,
      "additionalProperties": true,
      "description": "The snow evidence along the line, or null (snow_not_assessed below 800 m outside the snow months)."
    },
    "slopes": {
      "type": "object",
      "nullable": true,
      "additionalProperties": true,
      "description": "When asked: as POST /v1/route-slopes answers (experimental, slope at the path), or null."
    },
    "exits": {
      "type": "object",
      "nullable": true,
      "additionalProperties": true,
      "description": "When asked: as POST /v1/route-exits answers, with the no_exit_within_hour notice; a mapped way out, never a safe one."
    },
    "fires": {
      "type": "object",
      "nullable": true,
      "additionalProperties": true,
      "description": "Satellite heat detections (NASA FIRMS) within 10 km in the last 48 hours, placed along the line. A satellite saw heat: not a fire perimeter, and it can be a gas flare, industry or a volcano; the local fire service or authority decides closures. None found never means no fires. Credit NASA FIRMS (https://firms.modaps.eosdis.nasa.gov/) wherever a hotspot is shown."
    },
    "sun": {
      "type": "object",
      "nullable": true,
      "additionalProperties": true,
      "description": "When include has sun but not weather: the sun and shade along the line, as route weather’s sun block. With weather, sun sits inside the weather part."
    },
    "unknowns": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "part": {
            "type": "string"
          },
          "code": {
            "type": "string"
          },
          "message": {
            "type": "string"
          }
        },
        "required": [
          "code",
          "message"
        ],
        "additionalProperties": true
      }
    }
  },
  "required": [
    "schema",
    "engine",
    "include",
    "line",
    "notices",
    "unknowns"
  ],
  "additionalProperties": true
}

Route brief request fields
{
  "type": "object",
  "properties": {
    "gpx": {
      "type": "string",
      "description": "One line as GPX, one part, at most 120 km and 5,000 points. Or geometry, not both."
    },
    "geometry": {
      "type": "object",
      "additionalProperties": true,
      "description": "A GeoJSON LineString, [lon, lat]."
    },
    "include": {
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "analysis",
          "weather",
          "sun",
          "places",
          "snow",
          "fires",
          "slopes",
          "exits"
        ]
      },
      "description": "The parts to give; default all but slopes and exits, which are given only when asked."
    },
    "departure": {
      "type": "string",
      "description": "ISO 8601 with offset, six hours ago to 16 days ahead. Required with weather or sun, refused without them."
    },
    "profile": {
      "type": "string",
      "enum": [
        "hike",
        "run",
        "bike"
      ],
      "default": "hike"
    },
    "pace_factor": {
      "type": "number",
      "minimum": 0.5,
      "maximum": 2
    },
    "min_per_km": {
      "type": "number"
    },
    "kmh": {
      "type": "number"
    },
    "stops": {
      "type": "array",
      "items": {
        "type": "object",
        "additionalProperties": true
      }
    },
    "pace_profile": {
      "type": "object",
      "additionalProperties": true,
      "description": "Hike only: the pace_profile /v1/time-model/fit answered, sent unchanged. Adds the person’s own time (with an 80 % range) beside the model’s; refused with 422 pace_profile_stale after a refit of the model."
    }
  },
  "additionalProperties": true
}

Schema references resolve in the downloadable OpenAPI file. A shape check does not establish field accuracy or physical route suitability.

POST

Places along a route

/v1/route-places

Mapped drinking water, springs, huts, shelters and transport stops near a GPX or GeoJSON line, in order along it, each with metres along and off the line, its OSM tags exactly as tagged, and the longest stretch without mapped water. It says where water is mapped in OpenStreetMap, never that it runs: a tap may be off and a spring dry. Credits: 1 per started 25 km of line; each call also counts once toward the daily area ceiling.

Full reference, examples in curl, JavaScript and Python, and Try it →

Inspect request and response shapes
Places along a route request
curl --fail-with-body 'https://api.trailsplits.com/v1/route-places' \
  -H 'Content-Type: application/json' \
  --data '{"geometry":{"type":"LineString","coordinates":[[6.97178,45.79266],[6.98409,45.80185],[6.98629,45.80488],[6.98231,45.80634],[6.9782,45.80782],[6.9784,45.81286],[6.98961,45.82424],[7.00303,45.82901],[7.0139,45.83525],[7.02084,45.83669],[7.02859,45.84621],[7.03402,45.84664]]},"within_m":300}'

Places along a route contract
{
  "post": {
    "operationId": "route-places",
    "summary": "Places along a route",
    "description": "Mapped drinking water, springs, huts, shelters and transport stops near a GPX or GeoJSON line, in order along it, each with metres along and off the line, its OSM tags exactly as tagged, and the longest stretch without mapped water. It says where water is mapped in OpenStreetMap, never that it runs: a tap may be off and a spring dry. Credits: 1 per started 25 km of line; each call also counts once toward the daily area ceiling.",
    "tags": [
      "Developer preview"
    ],
    "security": [
      {},
      {
        "ApiKey": []
      }
    ],
    "parameters": [],
    "requestBody": {
      "required": true,
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/RoutePlacesInput"
          }
        }
      }
    },
    "responses": {
      "200": {
        "description": "Successful response; additive fields are allowed.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/RoutePlaces"
            }
          }
        }
      },
      "400": {
        "description": "Documented error/refusal; no result geometry should be fabricated.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ProductError"
            }
          }
        }
      },
      "413": {
        "description": "Documented error/refusal; no result geometry should be fabricated.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ProductError"
            }
          }
        }
      },
      "422": {
        "description": "Documented error/refusal; no result geometry should be fabricated.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ProductError"
            }
          }
        }
      },
      "503": {
        "description": "Documented error/refusal; no result geometry should be fabricated.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ProductError"
            }
          }
        }
      },
      "default": {
        "description": "Other gateway/provider failures are possible in preview. Consumers bound and surface them; do not treat an unknown status as success."
      }
    }
  }
}

Places along a route response fields
{
  "type": "object",
  "properties": {
    "schema": {
      "type": "string",
      "enum": [
        "route-places/1"
      ]
    },
    "engine": {
      "type": "object",
      "additionalProperties": true
    },
    "settings": {
      "type": "object",
      "additionalProperties": true
    },
    "settings_defaulted": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "input": {
      "type": "object",
      "properties": {
        "format": {
          "type": "string"
        },
        "parts": {
          "type": "integer"
        },
        "points": {
          "type": "integer"
        },
        "length_m": {
          "type": "number"
        },
        "gaps_m": {
          "type": "array",
          "items": {
            "type": "number"
          }
        }
      },
      "required": [
        "length_m"
      ],
      "additionalProperties": true
    },
    "source": {
      "type": "object",
      "properties": {
        "name": {
          "type": "string"
        },
        "licence": {
          "type": "string"
        },
        "version": {
          "type": "string"
        }
      },
      "required": [
        "name",
        "licence",
        "version"
      ],
      "additionalProperties": true
    },
    "places": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "at_m": {
            "type": "number",
            "description": "Along the line."
          },
          "offset_m": {
            "type": "number",
            "description": "Off the line."
          },
          "category": {
            "type": "string",
            "enum": [
              "water",
              "spring",
              "hut",
              "shelter",
              "transport"
            ]
          },
          "kind": {
            "type": "string"
          },
          "name": {
            "type": "string",
            "nullable": true
          },
          "lon": {
            "type": "number"
          },
          "lat": {
            "type": "number"
          },
          "ele_m": {
            "type": "number",
            "nullable": true
          },
          "osm_id": {
            "type": "string"
          },
          "osm_ids": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "tags": {
            "type": "object",
            "additionalProperties": true,
            "description": "Exactly as tagged."
          },
          "drinking_water_confirmed": {
            "type": "boolean",
            "description": "Water and springs: true only for mapped drinking water not tagged seasonal, intermittent, drinking_water=no or access=no/private/customers."
          }
        },
        "required": [
          "at_m",
          "offset_m",
          "category",
          "kind",
          "lon",
          "lat",
          "osm_ids",
          "tags"
        ],
        "additionalProperties": true
      }
    },
    "counts": {
      "type": "object",
      "additionalProperties": true
    },
    "water": {
      "type": "object",
      "nullable": true,
      "additionalProperties": true,
      "description": "When water or springs are asked: how many are mapped, and the longest stretches without mapped water, without untagged water, and without confirmed drinking water (longest_without_drinking_water, with how many other sources lie inside it that may be dry, not drinkable, private or for customers only)."
    },
    "unknowns": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "code": {
            "type": "string"
          },
          "message": {
            "type": "string"
          }
        },
        "required": [
          "code",
          "message"
        ],
        "additionalProperties": true
      }
    }
  },
  "required": [
    "schema",
    "engine",
    "input",
    "source",
    "places",
    "counts",
    "water",
    "unknowns"
  ],
  "additionalProperties": true
}

Places along a route request fields
{
  "type": "object",
  "properties": {
    "gpx": {
      "type": "string",
      "description": "One line as GPX (several parts allowed; distances skip the gaps). Or geometry, not both. Limits: 5,000 points, 300 km, 1 MB."
    },
    "geometry": {
      "type": "object",
      "additionalProperties": true,
      "description": "A GeoJSON LineString or MultiLineString, [lon, lat]."
    },
    "kinds": {
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "water",
          "spring",
          "hut",
          "shelter",
          "transport"
        ]
      },
      "description": "Default all."
    },
    "within_m": {
      "type": "number",
      "minimum": 10,
      "maximum": 1000,
      "default": 100,
      "description": "How far from the line a place may lie."
    }
  },
  "additionalProperties": true
}

Schema references resolve in the downloadable OpenAPI file. A shape check does not establish field accuracy or physical route suitability.

POST

Pace plan for a course

/v1/pace-plan

Splits every kilometre or mile for one course, from a target time or your pace on the flat: slower where it climbs or descends steeply (effort km = distance km + climb m / 100 + descent m / 300). Each split ends on its mark and names its terrain (steady climb, technical descent, …). Uses the file’s own heights, or the terrain model’s. The engine of the Pace & Split Calculator. A pacing rule, not a physiological model. 2 credits.

Full reference, examples in curl, JavaScript and Python, and Try it →

Inspect request and response shapes
Pace plan for a course request
curl --fail-with-body 'https://api.trailsplits.com/v1/pace-plan' \
  -H 'Content-Type: application/json' \
  --data '{"geometry":{"type":"LineString","coordinates":[[7.7475,46.0207],[7.74,46.018],[7.73,46.014],[7.7174,46.0091]]},"target_time":"0:20:00"}'

Pace plan for a course contract
{
  "post": {
    "operationId": "pace-plan",
    "summary": "Pace plan for a course",
    "description": "Splits every kilometre or mile for one course, from a target time or your pace on the flat: slower where it climbs or descends steeply (effort km = distance km + climb m / 100 + descent m / 300). Each split ends on its mark and names its terrain (steady climb, technical descent, …). Uses the file’s own heights, or the terrain model’s. The engine of the Pace & Split Calculator. A pacing rule, not a physiological model. 2 credits.",
    "tags": [
      "Developer preview"
    ],
    "security": [
      {},
      {
        "ApiKey": []
      }
    ],
    "parameters": [],
    "requestBody": {
      "required": true,
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/PacePlanInput"
          }
        }
      }
    },
    "responses": {
      "200": {
        "description": "Successful response; additive fields are allowed.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/PacePlan"
            }
          }
        }
      },
      "400": {
        "description": "Documented error/refusal; no result geometry should be fabricated.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ProductError"
            }
          }
        }
      },
      "413": {
        "description": "Documented error/refusal; no result geometry should be fabricated.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ProductError"
            }
          }
        }
      },
      "422": {
        "description": "Documented error/refusal; no result geometry should be fabricated.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ProductError"
            }
          }
        }
      },
      "default": {
        "description": "Other gateway/provider failures are possible in preview. Consumers bound and surface them; do not treat an unknown status as success."
      }
    }
  }
}

Pace plan for a course response fields
{
  "type": "object",
  "properties": {
    "schema": {
      "type": "string",
      "enum": [
        "pace-plan/1"
      ]
    },
    "engine": {
      "type": "object",
      "additionalProperties": true
    },
    "settings_defaulted": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "unit": {
      "type": "string",
      "enum": [
        "km",
        "mi"
      ]
    },
    "target": {
      "type": "object",
      "properties": {
        "kind": {
          "type": "string",
          "enum": [
            "time",
            "flat_pace"
          ]
        },
        "seconds": {
          "type": "number",
          "description": "The finish time the splits add up to, to 0.1 s."
        },
        "flat_pace_s_per_km": {
          "type": "number"
        }
      },
      "required": [
        "kind",
        "seconds"
      ],
      "additionalProperties": true
    },
    "course": {
      "type": "object",
      "properties": {
        "distance_m": {
          "type": "number"
        },
        "gain_m": {
          "type": "number"
        },
        "loss_m": {
          "type": "number"
        },
        "heights": {
          "type": "string",
          "enum": [
            "recorded",
            "terrain",
            "none"
          ]
        },
        "smoothing": {
          "type": "string"
        }
      },
      "required": [
        "distance_m",
        "gain_m",
        "loss_m",
        "heights",
        "smoothing"
      ],
      "additionalProperties": true
    },
    "effort": {
      "type": "object",
      "properties": {
        "rule": {
          "type": "string"
        },
        "flat_pace_s_per_km": {
          "type": "number",
          "description": "The pace on level ground that the target means on this course."
        }
      },
      "required": [
        "rule",
        "flat_pace_s_per_km"
      ],
      "additionalProperties": true
    },
    "splits": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "label": {
            "type": "string"
          },
          "from_m": {
            "type": "number"
          },
          "to_m": {
            "type": "number"
          },
          "distance_m": {
            "type": "number"
          },
          "gain_m": {
            "type": "number"
          },
          "loss_m": {
            "type": "number"
          },
          "pace_s_per_km": {
            "type": "number"
          },
          "seconds": {
            "type": "number"
          },
          "cumulative_seconds": {
            "type": "number"
          },
          "character": {
            "type": "string",
            "enum": [
              "runnable",
              "steady climb",
              "major climb",
              "fast descent",
              "technical descent",
              "rolling mountain terrain"
            ]
          }
        },
        "required": [
          "label",
          "from_m",
          "to_m",
          "distance_m",
          "gain_m",
          "loss_m",
          "pace_s_per_km",
          "seconds",
          "cumulative_seconds",
          "character"
        ],
        "additionalProperties": true
      }
    },
    "sections": {
      "type": "object",
      "nullable": true,
      "additionalProperties": true,
      "description": "Only with sections: true. The course-sections/1 record on the plan’s own heights, plus heights_source. Its climb is the route method, the same as course.gain_m since 7 October 2026: totals.ascent_m equals course.gain_m wherever every point carries a height."
    },
    "section_times": {
      "type": "array",
      "nullable": true,
      "description": "Only with sections: true: per terrain section id, kind, from_m, to_m, seconds and cumulative_seconds, the target’s moving time shared by effort. They add up to target.seconds; a section’s seconds can be 0 on a very flat line.",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "kind": {
            "type": "string"
          },
          "from_m": {
            "type": "number"
          },
          "to_m": {
            "type": "number"
          },
          "seconds": {
            "type": "number"
          },
          "cumulative_seconds": {
            "type": "number"
          }
        },
        "required": [
          "id",
          "kind",
          "from_m",
          "to_m",
          "seconds",
          "cumulative_seconds"
        ],
        "additionalProperties": true
      }
    },
    "checkpoints": {
      "type": "array",
      "description": "Only with checkpoints: per distance asked, in the order given: at_m, distance_m (where it was read: a distance past the finish reads the finish), gain_m, loss_m, effort_km and cumulative_seconds. At a split boundary cumulative_seconds equals that split’s.",
      "items": {
        "type": "object",
        "properties": {
          "at_m": {
            "type": "number"
          },
          "distance_m": {
            "type": "number"
          },
          "gain_m": {
            "type": "number"
          },
          "loss_m": {
            "type": "number"
          },
          "effort_km": {
            "type": "number"
          },
          "cumulative_seconds": {
            "type": "number"
          }
        },
        "required": [
          "at_m",
          "distance_m",
          "gain_m",
          "loss_m",
          "effort_km",
          "cumulative_seconds"
        ],
        "additionalProperties": true
      }
    },
    "unknowns": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "code": {
            "type": "string"
          },
          "message": {
            "type": "string"
          }
        },
        "required": [
          "code",
          "message"
        ],
        "additionalProperties": true
      }
    }
  },
  "required": [
    "schema",
    "engine",
    "unit",
    "target",
    "course",
    "effort",
    "splits",
    "unknowns"
  ],
  "additionalProperties": true
}

Pace plan for a course request fields
{
  "type": "object",
  "properties": {
    "gpx": {
      "type": "string",
      "description": "One line as GPX. Or geometry, not both. Limits: 5,000 points, 300 km, 1 MB; one part only."
    },
    "geometry": {
      "type": "object",
      "additionalProperties": true,
      "description": "A GeoJSON LineString, [lon, lat, height?]."
    },
    "target_time": {
      "type": "string",
      "description": "h:mm:ss, mm:ss or minutes, e.g. \"2:30:00\". One of target_time, target_seconds or flat_pace_s_per_km."
    },
    "target_seconds": {
      "type": "number"
    },
    "flat_pace_s_per_km": {
      "type": "number",
      "minimum": 120,
      "maximum": 1800,
      "description": "Your pace on level ground, seconds per km."
    },
    "sections": {
      "type": "boolean",
      "default": false,
      "description": "Sections mode: also answer the course’s course sections (course-sections/1) and section_times, each terrain section’s share of this plan’s time. The splits stay as they are. Added 6 October 2026."
    },
    "unit": {
      "type": "string",
      "enum": [
        "km",
        "mi"
      ],
      "default": "km",
      "description": "Splits every kilometre or mile; paces are always per kilometre."
    },
    "checkpoints": {
      "type": "array",
      "minItems": 1,
      "maxItems": 200,
      "items": {
        "type": "number",
        "minimum": 0
      },
      "description": "Distances along the course in metres (aid stations, cut-offs): the answer gives the plan’s effort and time at each, shared exactly as the splits share it. Added 13 October 2026."
    }
  },
  "additionalProperties": true
}

Schema references resolve in the downloadable OpenAPI file. A shape check does not establish field accuracy or physical route suitability.

POST

Clean a GPX file

/v1/gpx/clean

Removes repeated points and points with broken coordinates, and optionally every time stamp and sensor extension (heart rate, cadence, power). The file comes back as the file: only what was removed is cut; names, comments, CDATA, waypoints and indentation stay byte for byte. A report says what changed. Body at most 5 MB, 50,000 points.

Full reference, examples in curl, JavaScript and Python, and Try it →

Inspect request and response shapes
Clean a GPX file request
curl --fail-with-body 'https://api.trailsplits.com/v1/gpx/clean' \
  -H 'Content-Type: application/json' \
  --data '{"gpx":"<?xml version=\"1.0\" encoding=\"UTF-8\"?><gpx version=\"1.1\" creator=\"example\" xmlns=\"http://www.topografix.com/GPX/1/1\"><trk><name>Example</name><trkseg><trkpt lat=\"46.5369\" lon=\"12.1352\"><ele>1183</ele></trkpt><trkpt lat=\"46.5369\" lon=\"12.1352\"><ele>1183</ele></trkpt><trkpt lat=\"46.5365\" lon=\"12.1341\"><ele>1190</ele></trkpt><trkpt lat=\"46.5360\" lon=\"12.1330\"><ele>1195</ele></trkpt></trkseg></trk></gpx>"}'

Clean a GPX file contract
{
  "post": {
    "operationId": "gpx-clean",
    "summary": "Clean a GPX file",
    "description": "Removes repeated points and points with broken coordinates, and optionally every time stamp and sensor extension (heart rate, cadence, power). The file comes back as the file: only what was removed is cut; names, comments, CDATA, waypoints and indentation stay byte for byte. A report says what changed. Body at most 5 MB, 50,000 points.",
    "tags": [
      "Developer preview"
    ],
    "security": [
      {},
      {
        "ApiKey": []
      }
    ],
    "parameters": [],
    "requestBody": {
      "required": true,
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/GpxCleanInput"
          }
        }
      }
    },
    "responses": {
      "200": {
        "description": "Successful response; additive fields are allowed.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/GpxClean"
            }
          }
        }
      },
      "400": {
        "description": "Documented error/refusal; no result geometry should be fabricated.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ProductError"
            }
          }
        }
      },
      "413": {
        "description": "Documented error/refusal; no result geometry should be fabricated.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ProductError"
            }
          }
        }
      },
      "422": {
        "description": "Documented error/refusal; no result geometry should be fabricated.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ProductError"
            }
          }
        }
      },
      "default": {
        "description": "Other gateway/provider failures are possible in preview. Consumers bound and surface them; do not treat an unknown status as success."
      }
    }
  }
}

Clean a GPX file response fields
{
  "type": "object",
  "properties": {
    "schema": {
      "type": "string",
      "enum": [
        "gpx-clean/1"
      ]
    },
    "engine": {
      "type": "object",
      "additionalProperties": true
    },
    "settings": {
      "type": "object",
      "additionalProperties": true
    },
    "report": {
      "type": "object",
      "properties": {
        "changed": {
          "type": "boolean"
        },
        "points_before": {
          "type": "integer"
        },
        "points_after": {
          "type": "integer"
        },
        "duplicates": {
          "type": "integer"
        },
        "bad_coordinates": {
          "type": "integer"
        }
      },
      "required": [
        "changed",
        "points_before",
        "points_after"
      ],
      "additionalProperties": true
    },
    "gpx": {
      "type": "string",
      "description": "The cleaned file; byte for byte the input where nothing was removed."
    }
  },
  "required": [
    "schema",
    "report",
    "gpx"
  ],
  "additionalProperties": true
}

Clean a GPX file request fields
{
  "type": "object",
  "properties": {
    "gpx": {
      "type": "string",
      "description": "The GPX document. Body at most 5 MB, 50,000 points."
    },
    "dedupe": {
      "type": "boolean",
      "default": true
    },
    "drop_bad": {
      "type": "boolean",
      "default": true
    },
    "strip_times": {
      "type": "boolean",
      "default": false
    },
    "strip_extensions": {
      "type": "boolean",
      "default": false
    }
  },
  "required": [
    "gpx"
  ],
  "additionalProperties": true
}

Schema references resolve in the downloadable OpenAPI file. A shape check does not establish field accuracy or physical route suitability.

POST

Simplify a GPX file or line

/v1/gpx/simplify

Fewer points with the shape kept within a tolerance in ground metres (or a point budget), the climb protected and stops (waypoints, pauses of 10 minutes or more) kept in place. Reports the largest deviation and the distance and climb before and after. Answers equal the TrailSplits GPX Simplifier. Body at most 5 MB, 50,000 points.

Full reference, examples in curl, JavaScript and Python, and Try it →

Inspect request and response shapes
Simplify a GPX file or line request
curl --fail-with-body 'https://api.trailsplits.com/v1/gpx/simplify' \
  -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}'

Simplify a GPX file or line contract
{
  "post": {
    "operationId": "gpx-simplify",
    "summary": "Simplify a GPX file or line",
    "description": "Fewer points with the shape kept within a tolerance in ground metres (or a point budget), the climb protected and stops (waypoints, pauses of 10 minutes or more) kept in place. Reports the largest deviation and the distance and climb before and after. Answers equal the TrailSplits GPX Simplifier. Body at most 5 MB, 50,000 points.",
    "tags": [
      "Developer preview"
    ],
    "security": [
      {},
      {
        "ApiKey": []
      }
    ],
    "parameters": [],
    "requestBody": {
      "required": true,
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/GpxSimplifyInput"
          }
        }
      }
    },
    "responses": {
      "200": {
        "description": "Successful response; additive fields are allowed.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/GpxSimplify"
            }
          }
        }
      },
      "400": {
        "description": "Documented error/refusal; no result geometry should be fabricated.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ProductError"
            }
          }
        }
      },
      "413": {
        "description": "Documented error/refusal; no result geometry should be fabricated.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ProductError"
            }
          }
        }
      },
      "422": {
        "description": "Documented error/refusal; no result geometry should be fabricated.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ProductError"
            }
          }
        }
      },
      "default": {
        "description": "Other gateway/provider failures are possible in preview. Consumers bound and surface them; do not treat an unknown status as success."
      }
    }
  }
}

Simplify a GPX file or line response fields
{
  "type": "object",
  "properties": {
    "schema": {
      "type": "string",
      "enum": [
        "gpx-simplify/1"
      ]
    },
    "engine": {
      "type": "object",
      "additionalProperties": true
    },
    "settings": {
      "type": "object",
      "additionalProperties": true
    },
    "input": {
      "type": "object",
      "properties": {
        "format": {
          "type": "string"
        },
        "segments": {
          "type": "integer"
        },
        "points": {
          "type": "integer"
        }
      },
      "required": [
        "format",
        "segments",
        "points"
      ],
      "additionalProperties": true
    },
    "result": {
      "type": "object",
      "properties": {
        "points": {
          "type": "integer"
        },
        "removed": {
          "type": "integer"
        },
        "max_deviation_m": {
          "type": "number",
          "nullable": true
        }
      },
      "required": [
        "points",
        "removed"
      ],
      "additionalProperties": true
    },
    "gpx": {
      "type": "string"
    },
    "geometry": {
      "type": "object",
      "additionalProperties": true
    }
  },
  "required": [
    "schema",
    "input",
    "result"
  ],
  "additionalProperties": true
}

Simplify a GPX file or line request fields
{
  "type": "object",
  "properties": {
    "gpx": {
      "type": "string"
    },
    "geometry": {
      "type": "object",
      "additionalProperties": true
    },
    "tolerance_m": {
      "type": "number",
      "minimum": 0.5,
      "maximum": 1000,
      "default": 10
    },
    "max_points": {
      "type": "integer",
      "description": "Budget mode instead of tolerance_m."
    },
    "keep_climb": {
      "type": "boolean",
      "default": true
    },
    "keep_stops": {
      "type": "boolean",
      "default": true
    },
    "indices": {
      "type": "boolean",
      "default": false
    }
  },
  "additionalProperties": true
}

Schema references resolve in the downloadable OpenAPI file. A shape check does not establish field accuracy or physical route suitability.

GET

Places near a point

/search/v1/reverse

The nearest named places to a point, nearest first, with their distance in metres. Narrow to kinds (for example peak,hut,village) and widen the radius up to 50 km.

Parameters
Name / locationContract
lat · query · requiredLatitude.
lon · query · requiredLongitude.
limit · queryResults.
radius_m · querySearch radius in metres.
kinds · queryComma-separated kinds to keep.

Full reference, examples in curl, JavaScript and Python, and Try it →

Inspect request and response shapes
Places near a point request
curl --fail-with-body 'https://api.trailsplits.com/search/v1/reverse?lat=46.0207&lon=7.7491&limit=3'

Places near a point contract
{
  "get": {
    "operationId": "reverse",
    "summary": "Places near a point",
    "description": "The nearest named places to a point, nearest first, with their distance in metres. Narrow to kinds (for example peak,hut,village) and widen the radius up to 50 km.",
    "tags": [
      "Developer preview"
    ],
    "security": [
      {},
      {
        "ApiKey": []
      }
    ],
    "parameters": [
      {
        "name": "lat",
        "in": "query",
        "required": true,
        "schema": {
          "type": "number"
        },
        "description": "Latitude."
      },
      {
        "name": "lon",
        "in": "query",
        "required": true,
        "schema": {
          "type": "number"
        },
        "description": "Longitude."
      },
      {
        "name": "limit",
        "in": "query",
        "required": false,
        "schema": {
          "type": "integer",
          "minimum": 1,
          "maximum": 50,
          "default": 10
        },
        "description": "Results."
      },
      {
        "name": "radius_m",
        "in": "query",
        "required": false,
        "schema": {
          "type": "integer",
          "minimum": 50,
          "maximum": 50000,
          "default": 500
        },
        "description": "Search radius in metres."
      },
      {
        "name": "kinds",
        "in": "query",
        "required": false,
        "schema": {
          "type": "string"
        },
        "description": "Comma-separated kinds to keep."
      }
    ],
    "responses": {
      "200": {
        "description": "Successful response; additive fields are allowed.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ReverseResult"
            }
          }
        }
      },
      "400": {
        "description": "Documented error/refusal; no result geometry should be fabricated.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "default": {
        "description": "Other gateway/provider failures are possible in preview. Consumers bound and surface them; do not treat an unknown status as success."
      }
    }
  }
}

Places near a point response fields
{
  "type": "object",
  "properties": {
    "lat": {
      "type": "number"
    },
    "lon": {
      "type": "number"
    },
    "radius_m": {
      "type": "number"
    },
    "features": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer"
          },
          "name": {
            "type": "string"
          },
          "kind": {
            "type": "string"
          },
          "center": {
            "type": "array",
            "items": {
              "type": "number"
            }
          },
          "distance_m": {
            "type": "number"
          },
          "region": {
            "type": "string",
            "nullable": true
          }
        },
        "required": [
          "id",
          "name",
          "kind",
          "center",
          "distance_m"
        ],
        "additionalProperties": true
      }
    }
  },
  "required": [
    "lat",
    "lon",
    "radius_m",
    "features"
  ],
  "additionalProperties": true
}

Schema references resolve in the downloadable OpenAPI file. A shape check does not establish field accuracy or physical route suitability.

GET

Trail search

/trails/v1/search

Signed hiking and cycling routes (OpenStreetMap route relations) by name or reference, with network level, length and bounding box; the geometry is a representative point. Fetch a relation's full line with GET /trails/v1/relation/{osm_id}, or relations in an area with /trails/v1/bbox.

Parameters
Name / locationContract
q · query · requiredName or reference.
limit · queryResults.
type · queryRoute type.

Full reference, examples in curl, JavaScript and Python, and Try it →

Inspect request and response shapes
Trail search request
curl --fail-with-body 'https://api.trailsplits.com/trails/v1/search?q=Haute+Route&limit=3'

Trail search contract
{
  "get": {
    "operationId": "trails",
    "summary": "Trail search",
    "description": "Signed hiking and cycling routes (OpenStreetMap route relations) by name or reference, with network level, length and bounding box; the geometry is a representative point. Fetch a relation's full line with GET /trails/v1/relation/{osm_id}, or relations in an area with /trails/v1/bbox.",
    "tags": [
      "Developer preview"
    ],
    "security": [
      {},
      {
        "ApiKey": []
      }
    ],
    "parameters": [
      {
        "name": "q",
        "in": "query",
        "required": true,
        "schema": {
          "type": "string"
        },
        "description": "Name or reference."
      },
      {
        "name": "limit",
        "in": "query",
        "required": false,
        "schema": {
          "type": "integer",
          "minimum": 1,
          "maximum": 100,
          "default": 20
        },
        "description": "Results."
      },
      {
        "name": "type",
        "in": "query",
        "required": false,
        "schema": {
          "type": "string",
          "enum": [
            "hiking",
            "bicycle"
          ]
        },
        "description": "Route type."
      }
    ],
    "responses": {
      "200": {
        "description": "Successful response; additive fields are allowed.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/TrailSearchResult"
            }
          }
        }
      },
      "400": {
        "description": "Documented error/refusal; no result geometry should be fabricated.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "default": {
        "description": "Other gateway/provider failures are possible in preview. Consumers bound and surface them; do not treat an unknown status as success."
      }
    }
  }
}

Trail search response fields
{
  "type": "object",
  "properties": {
    "type": {
      "type": "string",
      "enum": [
        "FeatureCollection"
      ]
    },
    "query": {
      "type": "string"
    },
    "features": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "Feature"
            ]
          },
          "properties": {
            "type": "object",
            "properties": {
              "osm_relation_id": {
                "type": "integer"
              },
              "route_type": {
                "type": "string"
              },
              "name": {
                "type": "string"
              },
              "network": {
                "type": "string",
                "nullable": true
              },
              "distance_m": {
                "type": "number"
              },
              "bbox": {
                "type": "array",
                "items": {
                  "type": "number"
                }
              }
            },
            "required": [
              "osm_relation_id",
              "name"
            ],
            "additionalProperties": true
          },
          "geometry": {
            "type": "object",
            "properties": {
              "type": {
                "type": "string"
              },
              "coordinates": {
                "type": "array",
                "items": {
                  "type": "number"
                }
              }
            },
            "required": [
              "type",
              "coordinates"
            ],
            "additionalProperties": true
          }
        },
        "required": [
          "type",
          "properties",
          "geometry"
        ],
        "additionalProperties": true
      }
    }
  },
  "required": [
    "type",
    "query",
    "features"
  ],
  "additionalProperties": true
}

Schema references resolve in the downloadable OpenAPI file. A shape check does not establish field accuracy or physical route suitability.

GET

Trails in an area

/trails/v1/bbox

Signed hiking and cycling routes (OpenStreetMap route relations) that intersect a small box, each with its name, reference, network level, length, bounding box and a representative point. Note min_lng/max_lng here (lon for outdoor places). Counts toward the daily area ceiling.

Parameters
Name / locationContract
min_lat · query · requiredSouth edge.
min_lng · query · requiredWest edge (lng, not lon).
max_lat · query · requiredNorth edge.
max_lng · query · requiredEast edge.
type · queryRoute type.
limit · queryRelations.

Full reference, examples in curl, JavaScript and Python, and Try it →

Inspect request and response shapes
Trails in an area request
curl --fail-with-body 'https://api.trailsplits.com/trails/v1/bbox?min_lat=46&min_lng=7.74&max_lat=46.03&max_lng=7.77&type=hiking&limit=2'

Trails in an area contract
{
  "get": {
    "operationId": "trails-bbox",
    "summary": "Trails in an area",
    "description": "Signed hiking and cycling routes (OpenStreetMap route relations) that intersect a small box, each with its name, reference, network level, length, bounding box and a representative point. Note min_lng/max_lng here (lon for outdoor places). Counts toward the daily area ceiling.",
    "tags": [
      "Developer preview"
    ],
    "security": [
      {},
      {
        "ApiKey": []
      }
    ],
    "parameters": [
      {
        "name": "min_lat",
        "in": "query",
        "required": true,
        "schema": {
          "type": "number"
        },
        "description": "South edge."
      },
      {
        "name": "min_lng",
        "in": "query",
        "required": true,
        "schema": {
          "type": "number"
        },
        "description": "West edge (lng, not lon)."
      },
      {
        "name": "max_lat",
        "in": "query",
        "required": true,
        "schema": {
          "type": "number"
        },
        "description": "North edge."
      },
      {
        "name": "max_lng",
        "in": "query",
        "required": true,
        "schema": {
          "type": "number"
        },
        "description": "East edge."
      },
      {
        "name": "type",
        "in": "query",
        "required": false,
        "schema": {
          "type": "string",
          "enum": [
            "hiking",
            "bicycle"
          ]
        },
        "description": "Route type."
      },
      {
        "name": "limit",
        "in": "query",
        "required": false,
        "schema": {
          "type": "integer",
          "minimum": 1,
          "maximum": 5000,
          "default": 50
        },
        "description": "Relations."
      }
    ],
    "responses": {
      "200": {
        "description": "Successful response; additive fields are allowed.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/TrailBboxResult"
            }
          }
        }
      },
      "400": {
        "description": "Documented error/refusal; no result geometry should be fabricated.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "default": {
        "description": "Other gateway/provider failures are possible in preview. Consumers bound and surface them; do not treat an unknown status as success."
      }
    }
  }
}

Trails in an area response fields
{
  "type": "object",
  "properties": {
    "type": {
      "type": "string",
      "enum": [
        "FeatureCollection"
      ]
    },
    "features": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "Feature"
            ]
          },
          "properties": {
            "type": "object",
            "properties": {
              "osm_relation_id": {
                "type": "integer"
              },
              "route_type": {
                "type": "string"
              },
              "name": {
                "type": "string"
              },
              "network": {
                "type": "string",
                "nullable": true
              },
              "distance_m": {
                "type": "number"
              },
              "bbox": {
                "type": "array",
                "items": {
                  "type": "number"
                }
              }
            },
            "required": [
              "osm_relation_id",
              "name"
            ],
            "additionalProperties": true
          },
          "geometry": {
            "type": "object",
            "properties": {
              "type": {
                "type": "string"
              },
              "coordinates": {
                "type": "array",
                "items": {
                  "type": "number"
                }
              }
            },
            "required": [
              "type",
              "coordinates"
            ],
            "additionalProperties": true
          }
        },
        "required": [
          "type",
          "properties",
          "geometry"
        ],
        "additionalProperties": true
      }
    }
  },
  "required": [
    "type",
    "features"
  ],
  "additionalProperties": true
}

Schema references resolve in the downloadable OpenAPI file. A shape check does not establish field accuracy or physical route suitability.

GET

A trail relation’s line

/trails/v1/relation/{osm_id}

One signed route’s full line (LineString or MultiLineString, [lon, lat]) and its properties: name, reference, network level, length, climb where known, bounding box and point count. Large relations can be several hundred kB; the order of parts is not a walking order, and nothing here says the route is open or passable.

Parameters
Name / locationContract
osm_id · path · requiredThe OpenStreetMap relation id, as trail search and trails in an area give it.

Full reference, examples in curl, JavaScript and Python, and Try it →

Inspect request and response shapes
A trail relation’s line request
curl --fail-with-body 'https://api.trailsplits.com/trails/v1/relation/9235092' -o relation.json

A trail relation’s line contract
{
  "get": {
    "operationId": "trail-relation",
    "summary": "A trail relation’s line",
    "description": "One signed route’s full line (LineString or MultiLineString, [lon, lat]) and its properties: name, reference, network level, length, climb where known, bounding box and point count. Large relations can be several hundred kB; the order of parts is not a walking order, and nothing here says the route is open or passable.",
    "tags": [
      "Developer preview"
    ],
    "security": [
      {},
      {
        "ApiKey": []
      }
    ],
    "parameters": [
      {
        "name": "osm_id",
        "in": "path",
        "required": true,
        "schema": {
          "type": "integer",
          "minimum": 1
        },
        "description": "The OpenStreetMap relation id, as trail search and trails in an area give it."
      }
    ],
    "responses": {
      "200": {
        "description": "Successful response; additive fields are allowed.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/TrailRelation"
            }
          }
        }
      },
      "400": {
        "description": "Documented error/refusal; no result geometry should be fabricated.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "404": {
        "description": "Documented error/refusal; no result geometry should be fabricated.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "default": {
        "description": "Other gateway/provider failures are possible in preview. Consumers bound and surface them; do not treat an unknown status as success."
      }
    }
  }
}

A trail relation’s line response fields
{
  "type": "object",
  "properties": {
    "type": {
      "type": "string",
      "enum": [
        "Feature"
      ]
    },
    "properties": {
      "type": "object",
      "properties": {
        "osm_relation_id": {
          "type": "integer"
        },
        "route_type": {
          "type": "string"
        },
        "name": {
          "type": "string"
        },
        "ref": {
          "type": "string",
          "nullable": true
        },
        "network": {
          "type": "string",
          "nullable": true
        },
        "tier": {
          "type": "integer"
        },
        "distance_m": {
          "type": "number"
        },
        "ascent_m": {
          "type": "number"
        },
        "descent_m": {
          "type": "number"
        },
        "bbox": {
          "type": "array",
          "items": {
            "type": "number"
          },
          "description": "[minLon, minLat, maxLon, maxLat]"
        },
        "point_count": {
          "type": "integer"
        }
      },
      "required": [
        "osm_relation_id",
        "name",
        "bbox"
      ],
      "additionalProperties": true
    },
    "geometry": {
      "type": "object",
      "properties": {
        "type": {
          "type": "string",
          "enum": [
            "LineString",
            "MultiLineString"
          ]
        },
        "coordinates": {
          "type": "array",
          "items": {},
          "description": "[lon, lat] points (MultiLineString: one array per part)"
        }
      },
      "required": [
        "type",
        "coordinates"
      ],
      "additionalProperties": true
    }
  },
  "required": [
    "type",
    "properties",
    "geometry"
  ],
  "additionalProperties": true
}

Schema references resolve in the downloadable OpenAPI file. A shape check does not establish field accuracy or physical route suitability.

GET

Outdoor places in an area

/pois/v1/bbox

Huts, shelters and places to stay, places to eat, drinking water and springs, passes, parking, villages and transport stops in a small box, as flat records (lat, lon, ele and OSM tags as mapped), not GeoJSON Features. Viewpoints and peaks are not here: they are in search and the map tiles. Each side of the box may be at most 2°. artifact_version names the weekly release used.

Parameters
Name / locationContract
min_lat · query · requiredSouth.
min_lon · query · requiredWest.
max_lat · query · requiredNorth.
max_lon · query · requiredEast.
kind · queryComma-separated kinds, for example hut,shelter,water. An unknown kind matches nothing (no error). Without it, every kind.
limit · queryRecords.

Full reference, examples in curl, JavaScript and Python, and Try it →

Inspect request and response shapes
Outdoor places in an area request
curl --fail-with-body 'https://api.trailsplits.com/pois/v1/bbox?min_lat=46&min_lon=7.7&max_lat=46.05&max_lon=7.8&kind=hut&limit=5'

Outdoor places in an area contract
{
  "get": {
    "operationId": "pois",
    "summary": "Outdoor places in an area",
    "description": "Huts, shelters and places to stay, places to eat, drinking water and springs, passes, parking, villages and transport stops in a small box, as flat records (lat, lon, ele and OSM tags as mapped), not GeoJSON Features. Viewpoints and peaks are not here: they are in search and the map tiles. Each side of the box may be at most 2°. artifact_version names the weekly release used.",
    "tags": [
      "Developer preview"
    ],
    "security": [
      {},
      {
        "ApiKey": []
      }
    ],
    "parameters": [
      {
        "name": "min_lat",
        "in": "query",
        "required": true,
        "schema": {
          "type": "number"
        },
        "description": "South."
      },
      {
        "name": "min_lon",
        "in": "query",
        "required": true,
        "schema": {
          "type": "number"
        },
        "description": "West."
      },
      {
        "name": "max_lat",
        "in": "query",
        "required": true,
        "schema": {
          "type": "number"
        },
        "description": "North."
      },
      {
        "name": "max_lon",
        "in": "query",
        "required": true,
        "schema": {
          "type": "number"
        },
        "description": "East."
      },
      {
        "name": "kind",
        "in": "query",
        "required": false,
        "schema": {
          "type": "array",
          "items": {
            "type": "string",
            "enum": [
              "hut",
              "shelter",
              "guest_house",
              "hostel",
              "hotel",
              "camp_site",
              "chalet",
              "restaurant",
              "cafe",
              "pub",
              "station",
              "halt",
              "tram_stop",
              "bus_stop",
              "cable_car",
              "ferry_terminal",
              "water",
              "spring",
              "parking",
              "pass",
              "village",
              "town",
              "hamlet"
            ]
          }
        },
        "description": "Comma-separated kinds, for example hut,shelter,water. An unknown kind matches nothing (no error). Without it, every kind.",
        "style": "form",
        "explode": false
      },
      {
        "name": "limit",
        "in": "query",
        "required": false,
        "schema": {
          "type": "integer",
          "minimum": 1,
          "maximum": 10000,
          "default": 2000
        },
        "description": "Records."
      }
    ],
    "responses": {
      "200": {
        "description": "Successful response; additive fields are allowed.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/PoiBboxResult"
            }
          }
        }
      },
      "400": {
        "description": "Documented error/refusal; no result geometry should be fabricated.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "default": {
        "description": "Other gateway/provider failures are possible in preview. Consumers bound and surface them; do not treat an unknown status as success."
      }
    }
  }
}

Outdoor places in an area response fields
{
  "type": "object",
  "properties": {
    "type": {
      "type": "string",
      "enum": [
        "FeatureCollection"
      ]
    },
    "count": {
      "type": "integer"
    },
    "artifact_version": {
      "type": "string"
    },
    "features": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "kind": {
            "type": "string"
          },
          "name": {
            "type": "string",
            "nullable": true
          },
          "ele": {
            "type": "number",
            "nullable": true
          },
          "lat": {
            "type": "number"
          },
          "lon": {
            "type": "number"
          },
          "osm_id": {
            "type": "string",
            "nullable": true
          },
          "tags": {
            "type": "object",
            "additionalProperties": true
          }
        },
        "required": [
          "kind",
          "lat",
          "lon"
        ],
        "additionalProperties": true
      }
    }
  },
  "required": [
    "type",
    "features"
  ],
  "additionalProperties": true
}

Schema references resolve in the downloadable OpenAPI file. A shape check does not establish field accuracy or physical route suitability.

POST

Static map image

/static-map/render

A PNG of the outdoor map for a box, with an optional GeoJSON line or features drawn on it: for cards, emails and print. Attribution is drawn into the image; keep it visible.

Full reference, examples in curl, JavaScript and Python, and Try it →

Inspect request and response shapes
Static map image request
curl --fail-with-body 'https://api.trailsplits.com/static-map/render' \
  -H 'Content-Type: application/json' \
  --data '{"bbox":[12.13,46.535,12.137,46.538],"width":320,"height":200}' \
  -o map.png

Static map image contract
{
  "post": {
    "operationId": "static-map",
    "summary": "Static map image",
    "description": "A PNG of the outdoor map for a box, with an optional GeoJSON line or features drawn on it: for cards, emails and print. Attribution is drawn into the image; keep it visible.",
    "tags": [
      "Developer preview"
    ],
    "security": [
      {},
      {
        "ApiKey": []
      }
    ],
    "parameters": [],
    "requestBody": {
      "required": true,
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/StaticMapInput"
          }
        }
      }
    },
    "responses": {
      "200": {
        "description": "PNG image.",
        "content": {
          "image/png": {
            "schema": {
              "type": "string",
              "format": "binary"
            }
          }
        }
      },
      "400": {
        "description": "Documented error/refusal; no result geometry should be fabricated.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "503": {
        "description": "Documented error/refusal; no result geometry should be fabricated.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "default": {
        "description": "Other gateway/provider failures are possible in preview. Consumers bound and surface them; do not treat an unknown status as success."
      }
    }
  }
}

Static map image request fields
{
  "type": "object",
  "properties": {
    "bbox": {
      "type": "array",
      "minItems": 4,
      "maxItems": 4,
      "items": {
        "type": "number"
      },
      "description": "[minLon, minLat, maxLon, maxLat]"
    },
    "width": {
      "type": "integer",
      "minimum": 1,
      "maximum": 2000
    },
    "height": {
      "type": "integer",
      "minimum": 1,
      "maximum": 2000
    },
    "geojson": {
      "type": "object",
      "additionalProperties": true
    },
    "padding": {
      "type": "number"
    }
  },
  "required": [
    "bbox"
  ],
  "additionalProperties": true
}

Schema references resolve in the downloadable OpenAPI file. A shape check does not establish field accuracy or physical route suitability.

POST

Map matching and trace attributes

/valhalla/trace_attributes

Matches a line to the mapped network and returns each way it follows with surface (and whether the surface is mapped or a class default), use and SAC grade, plus the matched line per segment, unmatched stretches with reasons, and three lengths. Valhalla-compatible input; up to 2,000 points. Edge lengths are kilometres. For a full analysis with climb, time and unknowns use route analysis.

Full reference, examples in curl, JavaScript and Python, and Try it →

Inspect request and response shapes
Map matching and trace attributes request
curl --fail-with-body 'https://api.trailsplits.com/valhalla/trace_attributes' \
  -H 'Content-Type: application/json' \
  --data '{"shape":[{"lat":46.5369,"lon":12.1352},{"lat":46.536,"lon":12.133}],"costing":"pedestrian","shape_match":"map_snap"}'

Map matching and trace attributes contract
{
  "post": {
    "operationId": "trace-attributes",
    "summary": "Map matching and trace attributes",
    "description": "Matches a line to the mapped network and returns each way it follows with surface (and whether the surface is mapped or a class default), use and SAC grade, plus the matched line per segment, unmatched stretches with reasons, and three lengths. Valhalla-compatible input; up to 2,000 points. Edge lengths are kilometres. For a full analysis with climb, time and unknowns use route analysis.",
    "tags": [
      "Developer preview"
    ],
    "security": [
      {},
      {
        "ApiKey": []
      }
    ],
    "parameters": [],
    "requestBody": {
      "required": true,
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/TraceAttributesInput"
          }
        }
      }
    },
    "responses": {
      "200": {
        "description": "Successful response; additive fields are allowed.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/TraceAttributes"
            }
          }
        }
      },
      "400": {
        "description": "Documented error/refusal; no result geometry should be fabricated.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "422": {
        "description": "Documented error/refusal; no result geometry should be fabricated.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "default": {
        "description": "Other gateway/provider failures are possible in preview. Consumers bound and surface them; do not treat an unknown status as success."
      }
    }
  }
}

Map matching and trace attributes response fields
{
  "type": "object",
  "properties": {
    "edges": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "length": {
            "type": "number",
            "description": "Kilometres."
          },
          "begin_shape_index": {
            "type": "integer"
          },
          "end_shape_index": {
            "type": "integer"
          },
          "surface": {
            "type": "string",
            "nullable": true
          },
          "trailsplits_surface_tagged": {
            "type": "boolean"
          },
          "use": {
            "type": "string",
            "nullable": true
          },
          "sac_scale": {
            "type": "integer",
            "nullable": true
          }
        },
        "required": [
          "length"
        ],
        "additionalProperties": true
      }
    },
    "shape": {
      "type": "string",
      "description": "Polyline6 of the matched line, only when the match is one segment."
    },
    "units": {
      "type": "string",
      "enum": [
        "kilometers"
      ]
    },
    "trailsplits": {
      "type": "object",
      "properties": {
        "status": {
          "type": "string",
          "enum": [
            "matched",
            "partial",
            "unmatched"
          ]
        },
        "coverage": {
          "type": "number"
        },
        "trace_length_m": {
          "type": "number"
        },
        "matched_length_m": {
          "type": "number"
        },
        "segments": {
          "type": "array",
          "items": {
            "type": "object",
            "additionalProperties": true
          }
        },
        "unmatched": {
          "type": "array",
          "items": {
            "type": "object",
            "additionalProperties": true
          }
        }
      },
      "required": [
        "status",
        "coverage",
        "segments"
      ],
      "additionalProperties": true
    }
  },
  "required": [
    "edges",
    "trailsplits"
  ],
  "additionalProperties": true
}

Map matching and trace attributes request fields
{
  "type": "object",
  "properties": {
    "shape": {
      "type": "array",
      "minItems": 2,
      "maxItems": 2000,
      "items": {
        "type": "object",
        "properties": {
          "lat": {
            "type": "number"
          },
          "lon": {
            "type": "number"
          }
        },
        "required": [
          "lat",
          "lon"
        ],
        "additionalProperties": true
      }
    },
    "costing": {
      "type": "string",
      "enum": [
        "pedestrian",
        "bicycle"
      ]
    },
    "shape_match": {
      "type": "string",
      "enum": [
        "map_snap"
      ]
    }
  },
  "required": [
    "shape",
    "costing"
  ],
  "additionalProperties": true
}

Schema references resolve in the downloadable OpenAPI file. A shape check does not establish field accuracy or physical route suitability.

GET

Snow along a route

/tiles/v1/snow/route-forecast

Observed and recent snow cover at up to 512 sampled points, with 24 h and 48 h forecasts kept apart. With evidence=1 the answer carries route-snow-evidence/1: per-point class (snow, clear, unknown) and source, coverage, and a short validity. Unknown is never clear; narrow crossings between samples are not assessed. Points are lat,lon.

Parameters
Name / locationContract
points · query · requiredlat,lon pairs separated by |, at most 512.
evidence · queryAdd the route-snow-evidence/1 block.
revision · queryYour geometry version, echoed back (1–64 letters, digits or ._:-).
segments · queryStart indices of disconnected segments.

Full reference, examples in curl, JavaScript and Python, and Try it →

Inspect request and response shapes
Snow along a route request
curl --fail-with-body 'https://api.trailsplits.com/tiles/v1/snow/route-forecast?points=46.0207,7.7491%7C46,7.7&evidence=1&revision=example1'

Snow along a route contract
{
  "get": {
    "operationId": "snow",
    "summary": "Snow along a route",
    "description": "Observed and recent snow cover at up to 512 sampled points, with 24 h and 48 h forecasts kept apart. With evidence=1 the answer carries route-snow-evidence/1: per-point class (snow, clear, unknown) and source, coverage, and a short validity. Unknown is never clear; narrow crossings between samples are not assessed. Points are lat,lon.",
    "tags": [
      "Developer preview"
    ],
    "security": [
      {},
      {
        "ApiKey": []
      }
    ],
    "parameters": [
      {
        "name": "points",
        "in": "query",
        "required": true,
        "schema": {
          "type": "string"
        },
        "description": "lat,lon pairs separated by |, at most 512."
      },
      {
        "name": "evidence",
        "in": "query",
        "required": false,
        "schema": {
          "type": "integer",
          "enum": [
            1
          ]
        },
        "description": "Add the route-snow-evidence/1 block."
      },
      {
        "name": "revision",
        "in": "query",
        "required": false,
        "schema": {
          "type": "string"
        },
        "description": "Your geometry version, echoed back (1–64 letters, digits or ._:-)."
      },
      {
        "name": "segments",
        "in": "query",
        "required": false,
        "schema": {
          "type": "string"
        },
        "description": "Start indices of disconnected segments."
      }
    ],
    "responses": {
      "200": {
        "description": "Successful response; additive fields are allowed.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/SnowRoute"
            }
          }
        }
      },
      "400": {
        "description": "Documented error/refusal; no result geometry should be fabricated.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "503": {
        "description": "Documented error/refusal; no result geometry should be fabricated.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "default": {
        "description": "Other gateway/provider failures are possible in preview. Consumers bound and surface them; do not treat an unknown status as success."
      }
    }
  }
}

Snow along a route response fields
{
  "type": "object",
  "properties": {
    "evidence": {
      "type": "object",
      "properties": {
        "schema": {
          "type": "string",
          "enum": [
            "route-snow-evidence/1"
          ]
        },
        "revision": {
          "type": "string"
        },
        "valid_for": {
          "type": "string"
        },
        "sampling": {
          "type": "object",
          "properties": {
            "points": {
              "type": "integer"
            }
          },
          "required": [
            "points"
          ],
          "additionalProperties": true
        },
        "summary": {
          "type": "object",
          "properties": {
            "percent_snow": {
              "type": "number"
            },
            "percent_clear": {
              "type": "number"
            },
            "percent_unknown": {
              "type": "number"
            },
            "coverage": {
              "type": "string",
              "enum": [
                "full",
                "partial",
                "none"
              ]
            }
          },
          "required": [
            "percent_snow",
            "percent_clear",
            "percent_unknown",
            "coverage"
          ],
          "additionalProperties": true
        },
        "points": {
          "type": "array",
          "items": {
            "type": "object",
            "additionalProperties": true
          }
        }
      },
      "required": [
        "schema",
        "revision",
        "sampling",
        "summary",
        "points"
      ],
      "additionalProperties": true
    },
    "forecast_24h": {
      "type": "object",
      "additionalProperties": true
    },
    "forecast_48h": {
      "type": "object",
      "additionalProperties": true
    }
  },
  "required": [
    "evidence"
  ],
  "additionalProperties": true
}

Schema references resolve in the downloadable OpenAPI file. A shape check does not establish field accuracy or physical route suitability.

POST

Outdoor point-to-point route

/route/v1

Verified POST integration subset of Valhalla-compatible input; returns OSRM-shaped output with polyline6, metres and estimated seconds. Walking explicitly sets T3; running uses trailsplits.profile=run, cycling uses bicycle/hybrid. Unsupported car costing returns 400. No failure should become a straight-line route. Engine/settings and tile release are returned provenance, not immutable route replay. The Planner has a different site body/defaults; read /api/route/capabilities on trailsplits.com.

Run the outdoor routing example to inspect a live result or refusal.

Full reference, examples in curl, JavaScript and Python, and Try it →

Inspect request and response shapes
Outdoor point-to-point route request
curl --fail-with-body 'https://api.trailsplits.com/route/v1' \
  -H 'Content-Type: application/json' \
  --data '{"locations":[{"lat":46.5369,"lon":12.1352},{"lat":46.536,"lon":12.133}],"costing":"pedestrian","costing_options":{"pedestrian":{"max_hiking_difficulty":3}}}'

Outdoor point-to-point route contract
{
  "post": {
    "operationId": "route",
    "summary": "Outdoor point-to-point route",
    "description": "Verified POST integration subset of Valhalla-compatible input; returns OSRM-shaped output with polyline6, metres and estimated seconds. Walking explicitly sets T3; running uses trailsplits.profile=run, cycling uses bicycle/hybrid. Unsupported car costing returns 400. No failure should become a straight-line route. Engine/settings and tile release are returned provenance, not immutable route replay. The Planner has a different site body/defaults; read /api/route/capabilities on trailsplits.com.",
    "tags": [
      "Developer preview"
    ],
    "security": [
      {},
      {
        "ApiKey": []
      }
    ],
    "parameters": [],
    "requestBody": {
      "required": true,
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/RouteInput"
          }
        }
      }
    },
    "responses": {
      "200": {
        "description": "Successful response; additive fields are allowed.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Route"
            }
          }
        }
      },
      "400": {
        "description": "Documented error/refusal; no result geometry should be fabricated.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/RouteError"
            }
          }
        }
      },
      "422": {
        "description": "Documented error/refusal; no result geometry should be fabricated.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/RouteError"
            }
          }
        }
      },
      "503": {
        "description": "Documented error/refusal; no result geometry should be fabricated.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/RouteError"
            }
          }
        }
      },
      "default": {
        "description": "Other gateway/provider failures are possible in preview. Consumers bound and surface them; do not treat an unknown status as success."
      }
    }
  }
}

Outdoor point-to-point route response fields
{
  "type": "object",
  "properties": {
    "code": {
      "type": "string",
      "enum": [
        "Ok"
      ]
    },
    "routes": {
      "type": "array",
      "minItems": 1,
      "items": {
        "type": "object",
        "properties": {
          "geometry": {
            "type": "string",
            "minLength": 1,
            "description": "Polyline6; decoding yields lon,lat GeoJSON positions."
          },
          "distance": {
            "type": "number",
            "minimum": 0,
            "description": "Metres."
          },
          "duration": {
            "type": "number",
            "minimum": 0,
            "description": "Estimated seconds."
          }
        },
        "required": [
          "geometry",
          "distance",
          "duration"
        ],
        "additionalProperties": true
      }
    },
    "trailsplits": {
      "type": "object",
      "properties": {
        "engine": {
          "type": "object",
          "nullable": true,
          "additionalProperties": true,
          "description": "Available engine/tile/settings provenance; absent is unknown. Not a pinning parameter."
        },
        "warnings": {
          "type": "array",
          "items": {}
        },
        "summary": {
          "type": "object",
          "nullable": true,
          "additionalProperties": true
        }
      },
      "additionalProperties": true
    }
  },
  "required": [
    "code",
    "routes"
  ],
  "additionalProperties": true
}

Outdoor point-to-point route request fields
{
  "type": "object",
  "properties": {
    "locations": {
      "type": "array",
      "minItems": 2,
      "maxItems": 100,
      "items": {
        "type": "object",
        "properties": {
          "lat": {
            "type": "number",
            "minimum": -85.05,
            "maximum": 85.05
          },
          "lon": {
            "type": "number",
            "minimum": -180,
            "maximum": 180
          }
        },
        "required": [
          "lat",
          "lon"
        ],
        "additionalProperties": true
      }
    },
    "costing": {
      "type": "string",
      "enum": [
        "pedestrian",
        "bicycle",
        "auto"
      ],
      "description": "auto is included only to document its HTTP 400 refusal."
    },
    "trailsplits": {
      "type": "object",
      "properties": {
        "profile": {
          "type": "string",
          "enum": [
            "run"
          ]
        }
      },
      "required": [
        "profile"
      ],
      "additionalProperties": true
    },
    "costing_options": {
      "type": "object",
      "properties": {
        "pedestrian": {
          "type": "object",
          "properties": {
            "max_hiking_difficulty": {
              "type": "integer",
              "minimum": 1,
              "maximum": 6
            }
          },
          "required": [
            "max_hiking_difficulty"
          ],
          "additionalProperties": true
        },
        "bicycle": {
          "type": "object",
          "properties": {
            "bicycle_type": {
              "type": "string",
              "enum": [
                "hybrid"
              ]
            },
            "use_roads": {
              "type": "number",
              "minimum": 0,
              "maximum": 1
            },
            "use_ferry": {
              "type": "number",
              "minimum": 0,
              "maximum": 1
            }
          },
          "required": [
            "bicycle_type",
            "use_roads",
            "use_ferry"
          ],
          "additionalProperties": true
        }
      },
      "additionalProperties": true
    }
  },
  "required": [
    "locations",
    "costing"
  ],
  "additionalProperties": true
}

Schema references resolve in the downloadable OpenAPI file. A shape check does not establish field accuracy or physical route suitability.

Binary delivery has separate semantics

MapLibre consumes the published style and glyphs, vector tiles within PMTiles, and Mapbox-encoded TerrainRGB PNG tiles. The JSON reference deliberately does not pretend these are ordinary record APIs.

  • Resolve basemap, style and terrain independently from the manifest. Replace mutable style dependencies with compatible versioned addresses. Source dates can be null; promotion dates are different from source dates.
  • PMTiles v3 needs HTTP Range. The map example requires 206 and the exact requested length, cancelling a 200 whole-archive response. A 1,024-byte signature probe checks transport only; it does not validate the full archive or rendered map.
  • The fixed-view map is bounded to 128 assets / 16 MiB, 2 MiB per response plus two 256 KiB JSON requests. Terrain uses native z12 in the tested release and 1.2× visual exaggeration. More pixels or overzoom create no extra source detail.
  • The current style has no sprite-dependent layers. Its unused placeholder failed browser decoding on 2 October and is omitted explicitly by the example; a future sprite-dependent style must load valid pinned assets.
  • Keep the existing source-specific credits visible. Retained versions can retire, and public availability does not authorize every redistribution use.

Run the rendered map and inspect its actual artifact evidence. The terrain reference and basemap reference retain the fuller technical details.

How these are checked

Each operation on this page has a live probe: a fixed example request whose answer is checked for shape, units and meaning, not only for HTTP 200. The checks are bounded (a few small serial requests, no retries) and run after every release of the docs. A failing check keeps the operation out of this list until it passes again.