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
curl --fail-with-body 'https://api.trailsplits.com/healthz' {
"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
curl --fail-with-body 'https://api.trailsplits.com/pmtiles/current/manifest.json' {
"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."
}
}
}
} {
"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
curl --fail-with-body 'https://api.trailsplits.com/tiles/v1/status' {
"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."
}
}
}
} {
"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.
| Name / location | Contract |
|---|---|
release · path · required | Published terrain version, or mutable current. Demo resolves/pins a version. |
points · query · required | 1–2048 lat,lon pairs separated by |; example uses 8/16/32. |
z · query | Requested zoom; response z is the effective zoom. |
encoding · query | Use 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
# 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' {
"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."
}
}
}
} {
"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.
| Name / location | Contract |
|---|---|
p · query · required | 1–12 points as lat,lon[,elevation_m] separated by ;. Coordinates are rounded to 2 decimals (about 1 km) and echoed rounded. |
d · query | Forecast days. |
fl · query | Add the hourly freezing level. |
h · query | 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. |
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
curl --fail-with-body 'https://trailsplits.com/api/weather/forecast?p=46.0207,7.7491,1608&d=2' {
"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."
}
}
}
} {
"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
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"}' {
"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."
}
}
}
} {
"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
} {
"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
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"}' {
"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."
}
}
}
} {
"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
} {
"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
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. {
"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."
}
}
}
} {
"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
} {
"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
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}' {
"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."
}
}
}
} {
"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
} {
"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
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]]}' {
"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."
}
}
}
} {
"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
} {
"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
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]]}}' {
"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."
}
}
}
} {
"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
} {
"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
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}' {
"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."
}
}
}
} {
"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
} {
"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
# 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 {
"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."
}
}
}
} {
"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
} {
"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
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 {
"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."
}
}
}
} {
"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
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"]}' {
"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."
}
}
}
} {
"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
} {
"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
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]]}}' {
"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."
}
}
}
} {
"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
} {
"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
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"]}' {
"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."
}
}
}
} {
"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
} {
"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
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}' {
"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."
}
}
}
} {
"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
} {
"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
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"}' {
"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."
}
}
}
} {
"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
} {
"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
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>"}' {
"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."
}
}
}
} {
"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
} {
"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
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}' {
"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."
}
}
}
} {
"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
} {
"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
Place search
/search/v1/forward
Places and signed trails by name: towns, peaks, passes, lakes, huts, stations and more. A bias_bbox lifts places in the map view without excluding others. Misspellings and German ue/oe/ae spellings are found when nothing matches exactly (match: fuzzy). Coordinates are [lon, lat]. Not an address geocoder.
| Name / location | Contract |
|---|---|
q · query · required | The name, at least 2 letters. "Name, Place" searches near that place; "Place station" finds its railway stations. |
limit · query | Results. |
bias_bbox · query | minLon,minLat,maxLon,maxLat: a soft preference for the map view. |
bbox · query | minLon,minLat,maxLon,maxLat: a hard filter. |
Full reference, examples in curl, JavaScript and Python, and Try it →
Inspect request and response shapes
curl --fail-with-body 'https://api.trailsplits.com/search/v1/forward?q=Matterhorn&limit=3&bias_bbox=7.5,45.9,7.9,46.1' {
"get": {
"operationId": "search",
"summary": "Place search",
"description": "Places and signed trails by name: towns, peaks, passes, lakes, huts, stations and more. A bias_bbox lifts places in the map view without excluding others. Misspellings and German ue/oe/ae spellings are found when nothing matches exactly (match: fuzzy). Coordinates are [lon, lat]. Not an address geocoder.",
"tags": [
"Developer preview"
],
"security": [
{},
{
"ApiKey": []
}
],
"parameters": [
{
"name": "q",
"in": "query",
"required": true,
"schema": {
"type": "string"
},
"description": "The name, at least 2 letters. \"Name, Place\" searches near that place; \"Place station\" finds its railway stations."
},
{
"name": "limit",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 50,
"default": 10
},
"description": "Results."
},
{
"name": "bias_bbox",
"in": "query",
"required": false,
"schema": {
"type": "string"
},
"description": "minLon,minLat,maxLon,maxLat: a soft preference for the map view."
},
{
"name": "bbox",
"in": "query",
"required": false,
"schema": {
"type": "string"
},
"description": "minLon,minLat,maxLon,maxLat: a hard filter."
}
],
"responses": {
"200": {
"description": "Successful response; additive fields are allowed.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SearchResult"
}
}
}
},
"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."
}
}
}
} {
"type": "object",
"properties": {
"query": {
"type": "string"
},
"features": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Place"
}
}
},
"required": [
"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
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.
| Name / location | Contract |
|---|---|
lat · query · required | Latitude. |
lon · query · required | Longitude. |
limit · query | Results. |
radius_m · query | Search radius in metres. |
kinds · query | Comma-separated kinds to keep. |
Full reference, examples in curl, JavaScript and Python, and Try it →
Inspect request and response shapes
curl --fail-with-body 'https://api.trailsplits.com/search/v1/reverse?lat=46.0207&lon=7.7491&limit=3' {
"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."
}
}
}
} {
"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.
| Name / location | Contract |
|---|---|
q · query · required | Name or reference. |
limit · query | Results. |
type · query | Route type. |
Full reference, examples in curl, JavaScript and Python, and Try it →
Inspect request and response shapes
curl --fail-with-body 'https://api.trailsplits.com/trails/v1/search?q=Haute+Route&limit=3' {
"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."
}
}
}
} {
"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.
| Name / location | Contract |
|---|---|
min_lat · query · required | South edge. |
min_lng · query · required | West edge (lng, not lon). |
max_lat · query · required | North edge. |
max_lng · query · required | East edge. |
type · query | Route type. |
limit · query | Relations. |
Full reference, examples in curl, JavaScript and Python, and Try it →
Inspect request and response shapes
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' {
"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."
}
}
}
} {
"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.
| Name / location | Contract |
|---|---|
osm_id · path · required | The 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
curl --fail-with-body 'https://api.trailsplits.com/trails/v1/relation/9235092' -o relation.json {
"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."
}
}
}
} {
"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.
| Name / location | Contract |
|---|---|
min_lat · query · required | South. |
min_lon · query · required | West. |
max_lat · query · required | North. |
max_lon · query · required | East. |
kind · query | Comma-separated kinds, for example hut,shelter,water. An unknown kind matches nothing (no error). Without it, every kind. |
limit · query | Records. |
Full reference, examples in curl, JavaScript and Python, and Try it →
Inspect request and response shapes
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' {
"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."
}
}
}
} {
"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
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 {
"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."
}
}
}
} {
"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
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"}' {
"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."
}
}
}
} {
"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
} {
"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.
| Name / location | Contract |
|---|---|
points · query · required | lat,lon pairs separated by |, at most 512. |
evidence · query | Add the route-snow-evidence/1 block. |
revision · query | Your geometry version, echoed back (1–64 letters, digits or ._:-). |
segments · query | Start indices of disconnected segments. |
Full reference, examples in curl, JavaScript and Python, and Try it →
Inspect request and response shapes
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' {
"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."
}
}
}
} {
"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
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}}}' {
"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."
}
}
}
} {
"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
} {
"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.