Route through waypoints
POST https://api.trailsplits.com/v1/route
Checked by a live probe Key optional · 500 credits a day without one 1 credit per call (per 10 waypoints)
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.
Example
# Without a key, leave out the Authorization line (500 credits a day per address).
curl --fail-with-body 'https://api.trailsplits.com/v1/route' \
-H "Authorization: Bearer $TRAILSPLITS_API_KEY" \
-H 'Content-Type: application/json' \
--data '{"waypoints":[[7.7475,46.0207],[7.7174,46.0091],[7.7355,46.0036]]}' Request body
| Field | Type | Description |
|---|---|---|
waypointsrequired | array | 2 to 100 points, [lon, lat]. A leg (between two waypoints) may be at most 60 km in a straight line. |
profile | string: hike | run | bike | |
max_sac | integer | Hike and run: the hardest SAC grade allowed, 1 (T1) to 6 (T6). Refused for a bike. |
marked_trails | string: strict | prefer | off | Hike and run: how strongly to keep to waymarked trails. Refused for a bike. |
avoid_paved | boolean | |
hills | number | From -1 (avoid climbing) to 1 (seek it). |
shortest | boolean | The shortest route under the other settings, not the most suitable. |
bicycle_type | string: road | hybrid | mountain | Bike only. |
straight_legs | array | Leg numbers, counted from 0 (leg 0 joins waypoint 0 to waypoint 1), to draw straight, on no mapped path. |
snap_radius_m | number | How far a waypoint may lie from a usable path. |
Response
| Field | Type | Description |
|---|---|---|
schema | string: route/1 | |
engine | object | |
status | string: complete | best_effort | complete: every leg is a proven cheapest path under the settings. best_effort: a leg hit the search budget (a warning says which). |
settings | object | What was applied, in the request’s words. |
settings_defaulted | array | |
distance_m | number | |
ascent_m | number | |
descent_m | number | |
ascent_method | string | |
time | object or null | 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 | object | Paved, gravel, trail and unknown metres; mapped or assumed from the kind of way; stretches placed along the route. |
hazards | array | |
ways | object | |
difficulty | object or null | SAC-tagged metres by grade, untagged path and road metres, and the hardest stretch. |
warnings | array | |
unknowns | array | |
geometry | object | |
legs | array | |
snaps | array | |
maneuvers | array | |
cap_alternative | object or null | When the grade cap was left at its default and a harder path is much shorter: its max_sac, distance, climb and minutes. |
Full response schema (JSON Schema)
{
"type": "object",
"properties": {
"schema": {
"type": "string",
"enum": [
"route/1"
]
},
"engine": {
"type": "object"
},
"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",
"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,
"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",
"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"
]
}
},
"ways": {
"type": "object"
},
"difficulty": {
"type": "object",
"nullable": 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"
]
}
},
"unknowns": {
"type": "array",
"items": {
"type": "object",
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
}
},
"required": [
"code",
"message"
]
}
},
"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"
]
},
"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"
]
}
},
"snaps": {
"type": "array",
"items": {
"type": "object"
}
},
"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"
]
}
},
"cap_alternative": {
"type": "object",
"nullable": 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"
]
}Errors
400, 413, 422, 503, plus the gateway's 401, 429 and 503 (every error code). A refused request costs no credits.
Contract
A walking, running or cycling route through your waypoints, in the /v1 family's style:
-
[lon, lat]waypoints and flat snake_case settings; - the route as a GeoJSON line, with its legs;
- the facts that round trips and route analysis give: climb, the hike time with its scope, surfaces, ways, tagged grades, fords and aided passages, and every unknown;
-
errors as
{ "error": { "code", "message" } }.
Request
{ "waypoints": [[7.7475, 46.0207], [7.7174, 46.0091], [7.7355, 46.0036]] }
{ "waypoints": [[8.4926, 47.3631], [8.4913, 47.3496]], "profile": "run", "max_sac": 2, "marked_trails": "strict" }
{ "waypoints": [[8.5402, 47.3779], [8.5417, 47.3667]], "profile": "bike", "bicycle_type": "hybrid" }
| Field | Default | |
|---|---|---|
waypoints | required | 2 to 100 points, [lon, lat]. A leg (between two waypoints) may be at most 60 km in a straight line |
profile | hike | hike, run or bike |
max_sac | 3 | Hike and run: the hardest SAC grade allowed, 1 (T1) to 6 (T6). Paths tagged harder are never used. When it is left at 3 and a harder path would be much shorter, a warning and cap_alternative say so |
marked_trails | prefer | Hike and run: strict (strongly prefer waymarked trails), prefer or off. Bikes: off |
avoid_paved | false | Prefer unpaved ways |
hills | 0 | −1 (avoid climbing) to 1 (seek it) |
shortest | false | The shortest route under the other settings, not the most suitable |
bicycle_type | Bike: road, hybrid, cross or mountain (cross since 5 Oct 2026) | |
use_roads | Bike: 0 (keep off roads where it can) to 1 (roads are fine); the router's own middle when not given. Added 5 Oct 2026 | |
use_ferry | false | Bike: allow ferries. Added 5 Oct 2026 |
straight_legs | [] | Leg numbers (0 joins the first waypoint to the second) to draw straight, on no mapped path: across a glacier or a beach, say |
snap_radius_m | How far a waypoint may lie from a usable path, 10 to 5,000 m | |
avoid_points | [] | Up to 50 [lon, lat]: the way nearest each (within 50 m) is not used, for a closed bridge or a path you know is gone. Added 5 Oct 2026 |
caller | Optional label for logs and receipts |
A bike's settings are those of /route/v1 and the Planner: no grade cap below T6, marked trails off. max_sac and marked_trails are refused for a bike, and bicycle_type, use_roads and use_ferry for hike and run.
Counting. In fields, waypoints and legs count from 0 (legs[].leg, straight_legs, snaps[].waypoint); in messages they count from 1, as people do ("leg 1 is 62.6 km").
Response
| Field | Meaning |
|---|---|
schema | route/1 |
status | complete: every leg is a proven cheapest path under the settings. best_effort: a leg hit the search budget and is the best route seen when it stopped (a search_budget_exhausted warning says which) |
settings, settings_defaulted | What was applied, in the request's words, and which fields were not given. snap_radius_m null is the router's own radius for the profile |
distance_m | Along the route |
router_duration_s | The router's own speed model, every profile. For hike, time is the calibrated figure to quote; for run and bike this is the router's costing time, not an estimate (time stays null with time_not_estimated). Added 5 Oct 2026 |
time | Hike only: the calibrated trailsplits-hike/2 model's moving time, with applies (marked paths up to T3), its held-out error, outside_calibration with reasons, every named model's minutes, rough_share (the share of rough ground on the route's own edges that the time used), and region and notes as in round trips. Null for run and bike (time_not_estimated) |
surfaces | Paved, gravel, trail and unknown metres; what is mapped and what is assumed from the kind of way; stretches placed along the route; details_m, metres by detail (asphalt, paved, gravel, unpaved, natural, unknown; added 5 Oct 2026) |
segments[] | Every stretch of one way along the route, for a map layer (added 5 Oct 2026): from_m, to_m, way_type, sac_scale (T1…T6 or null), surface, surface_detail, source (mapped, class_default, unknown), marked, network (iwn, nwn, rwn, lwn or null), relation_id, way_id, name. The waymark colour is not given |
signed_trails | marked_m, unmarked_m, by_network_m (metres on signed hiking routes by network); null when the tiles do not say. Added 5 Oct 2026 |
hazards[] | kind (ford, aid, via_ferrata), from_m, to_m, length_m, way_id |
ways | Metres by way type; marked metres; max_sac; ford, aided, informal and steps metres |
difficulty | SAC-tagged metres by grade, untagged path metres, road metres, and the hardest stretch placed |
warnings[] | code, message, location ([lon, lat] or null); leg and meters where they apply (a straight leg, a defaulted grade cap) |
unknowns[] | code, message, length_m where it applies: as for round trips |
geometry | GeoJSON LineString, [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. The Planner in the browser keeps the graph's heights, so its figures for the same line can differ |
legs[] | leg, distance_m, ascent_m, descent_m, and how far the route left each end's waypoint to join a path (from_snap_m, to_snap_m) |
snaps[] | Where joint snapping placed each waypoint, when it ran (it runs when a waypoint's nearest paths make a detour): waypoint (from 0), location, distance_m, nearest_m. Empty otherwise. A waypoint moved off its nearest path for another reason shows as a snap_moved warning with its location, and one more than 50 m from its path as start_snapped or end_snapped |
maneuvers[] | instruction, type, modifier, ways (how many ways meet at the junction, or null; added 5 Oct 2026), name, location; distance_m is the stretch leading up to this step from the one before |
cap_alternative | When the grade cap was left at its default and a harder path is much shorter: max_sac ("T4"), max_sac_level (4; added 5 Oct 2026), distance_m, ascent_m, minutes; else null |
timing | Milliseconds and work, for logs |
Errors
Every refusal also carries docs (this page's code on /api/errors), and field, limit and got, hint, retry_after or request_id where they apply, as the error standard describes (api-errors-v1, since 6 Oct 2026).
{ "error": { "code", "message" } }.
| HTTP | code | When |
|---|---|---|
| 400 | invalid_request | Not JSON, an unknown field (including settings and locations), fewer than two or more than 100 waypoints, a waypoint off the map, a setting out of range or for the wrong profile |
| 400 | invalid_json | The body (or ?json=) is not valid JSON: send one JSON object with Content-Type: application/json |
| 405 | method_not_allowed | Any method but POST (and OPTIONS) |
| 413 | body_too_large | Over 1 MB |
| 422 | leg_too_long | A leg over 60 km in a straight line: add waypoints |
| 422 | snap_failed | A waypoint is farther than the snap radius from any path the settings allow |
| 422 | no_path_under_settings, no_path_in_corridor, disconnected | No path joins two waypoints under the settings, or none within the area searched; the message names the leg, and the error carries cap_alternative when a harder grade would join them |
| 422 | bad_straight_leg | A straight leg the router cannot draw |
| 422 | budget_exhausted, corridor_too_large | The search ran out of budget, or the area is too large for one request: add waypoints |
| 503 | overloaded | The worker's heavy-job queue is full; or, for a request of one leg, the API worker is behind and it would wait more than about a second to start (since 5 Oct 2026). Refused at once with Retry-After |
Versioning
Additive fields may appear in route/1. A change of meaning or a removed field is route/2.