Round trips from a start point
POST https://api.trailsplits.com/v1/roundtrips
Checked by a live probe Key optional · 500 credits a day without one 10 credits per call Heavy: 1 at a time on Free
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).
Example
# Without a key, leave out the Authorization line (500 credits a day per address).
curl --fail-with-body 'https://api.trailsplits.com/v1/roundtrips' \
-H "Authorization: Bearer $TRAILSPLITS_API_KEY" \
-H 'Content-Type: application/json' \
--data '{"start":[7.7491,46.0207],"distance_km":12,"profile":"hike"}' Request body
| Field | Type | Description |
|---|---|---|
startrequired | array | [lon, lat] |
distance_km | number | 0.5–40 km for hike and run, to 60 km for bike. Or distance_m, not both. |
distance_m | number | |
profile | string: hike | run | bike | |
direction | number or null | |
alternatives | integer | |
max_sac | integer | |
avoid_paved | boolean | |
hills | number | |
bicycle_type | string: road | hybrid | mountain | |
strategy | string: graph | ring | auto | 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 | object | 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. |
Response
| Field | Type | Description |
|---|---|---|
schema | string: roundtrips/1 | |
engine | object | |
status | string: complete | rough | |
reason | string or null | |
strategy | string: graph | ring | auto | The strategy used. |
request | object | |
search | object | The engine’s counters; version skipped with strategy ring. With rings, ring: probes, routed, kept, ms, stopped. |
loops | array |
Full response schema (JSON Schema)
{
"type": "object",
"properties": {
"schema": {
"type": "string",
"enum": [
"roundtrips/1"
]
},
"engine": {
"type": "object"
},
"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"
},
"search": {
"type": "object",
"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"
]
}
}
},
"required": [
"schema",
"engine",
"status",
"loops"
]
}Errors
400, 422, plus the gateway's 401, 429 and 503 (every error code). A refused request costs no credits.
Contract
Give a start and a length; get back loops that start and end there, as the TrailSplits Planner builds them, each with the facts route analysis gives: surfaces, ways, tagged grades, climb, the hike time with its scope, and what is not known. When no good loop exists, the answer says so.
Request
{ "start": [7.7491, 46.0207], "distance_km": 12, "profile": "hike", "alternatives": 2 }
| Field | ||||
|---|---|---|---|---|
start | [lon, lat] | Where the loop starts and ends | ||
distance_km or distance_m | number | One of them, not both: the length to aim for. Limits: 0.5 to 40 km for hike and run, to 60 km for bike (below). TrailSplits' own pages (the Planner, Explore, the training autopilot) ask on the internal pool up to 200 km (6 Oct 2026); the public limits are unchanged | ||
profile | hike \ | run \ | bike | Default hike |
direction | bearing in degrees, or null | A preference, not a rule: loops heading that way score better, and the best loop may still head elsewhere when the ground there is much better. Default null (any) | ||
alternatives | 0 to 3 | Loops from other directions besides the best; default 0 | ||
max_sac | 1 to 6 | hike and run only: the hardest tagged SAC grade used; default 3 (T3). A tagged grade above it is never used; untagged paths are unknown, never "easy" | ||
avoid_paved | boolean | Default false | ||
hills | −1 to 1 | −1 avoids climbing, 1 seeks it; default 0 | ||
bicycle_type | road \ | hybrid \ | mountain | bike only; default the router's hybrid |
caller | string | Optional label for logs and receipts |
Defaults are listed in request.settings_defaulted. Unknown fields and fields that do not apply (max_sac on a bike) are refused, not ignored.
Response
| Field | Meaning |
|---|---|
schema | roundtrips/1 |
reason | Why the best loop is rough, or why there is none; else null |
strategy | The strategy used (added 6 Oct 2026) |
request | start, target_m, profile, direction, alternatives, strategy, settings (the router's), settings_defaulted |
loops[] | The best first (rank 0), then the alternatives |
search | The engine's own counters (version, tree nodes, candidates, pairs routed, ms, and stopped when the budget ended the search early; version: skipped with strategy: ring). With rings, ring: probes tried, routed, kept (within 40–200 % of the target), ms, stopped. A long loop (over 100 km, or wherever the graph loop's corridor would pass 64 tiles) searches no graph loop: long_loop: true, version: skipped, and rings each routed on a corridor of their own, their circles scaled by how much longer the routed rings run than their circles (corridors_refused counts the probes whose corridor was too large). Such a search keeps the best three rings between probes, so kept is at most 3 |
timing | Tiles and milliseconds |
climb_target | Only with a climb_target request: met (whether the best loop reproduces it), summits (summits found), summit_rings_routed, reason (why no loop can, e.g. "Nothing within 3.0 km of the start rises more than 29 m above it"; else null) |
Each loop:
| Field | Meaning |
|---|---|
engine | graph or ring: where this loop came from (added 6 Oct 2026) |
status | complete or rough, by the rule above |
score | How the loop ranks (added 6 Oct 2026), each part 0–1: length_fit (√ of the shorter over the longer of length and target), clean (1 with nothing walked twice, falling past 8 %; the larger of repeated_share and second_pass_share), marked (the share on marked trails; null for bike), and total = 0.5 × length fit + 0.35 × clean + 0.15 × marked (without marked, the first two over 0.85). With rings, loops are ranked complete before rough, then by total, alternatives at least 45° apart in bearing |
distance_m, target_m, target_error_pct | The length, the target, and the signed error in per cent |
repeated_m, repeated_share | Metres walked twice: the same mapped way used again |
stem_m | Of those, the way out from the start and back along the same path (a start at the end of a spur) |
spur_m | Of those, dead ends walked into and back out of at the turn points |
turn_points | The loop's two turn points, [lon, lat]; a ring's waypoints |
bearing_deg | Mean bearing of the turn points from the start; a ring's: the direction of its circle's centre |
quality | Cost per metre over the settings' best ground (1 is all best-case ground); null for a ring loop (the router keeps no cost for it) |
shape | The loop, polyline6 |
surfaces | As in route analysis: paved_m, gravel_m, trail_m, unknown_m, mapped_m, class_default_m, stretches[] along the loop |
ways | by_type_m, marked_m, max_sac, ford_m, aid_m, informal_m, steps_m |
hazards[] | As in route analysis: each ford, aided passage and via ferrata, with from_m and to_m in metres along the loop from the start |
difficulty | As in route analysis: graded_m (T1…T6), untagged_path_m, road_m, hardest |
warnings[] | The router's own (code, message): fords, aided passages, informal paths, high or unknown difficulty, pushing a bike, a start moved to a reachable path. Their figures are the router's: its unknown_difficulty counts untagged paths, tracks and bridleways, while unknowns.difficulty_untagged also counts footpaths and steps, so the two can differ |
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, unknown field, a field that does not apply, a value out of range, start not [lon, lat] or off the map, no distance, both distance fields, a distance under 0.5 km |
| 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; the answer carries Allow: POST |
| 409 | capability_unavailable | bike while the served routing tiles carry no verified one-ways or turn restrictions (as the Planner's loops) |
| 413 | body_too_large | The body is over 1 MB |
| 422 | too_long | Over 40 km on foot or 60 km by bike, checked on the length the engine will build |
| 422 | no_loop | No loop: the start is not near a path the settings may use, or none was found. The body also carries status: none, reason, request and search |
| 422 | corridor_too_large | The area the loop needs is too dense or too large to load |
| 503 | overloaded | The worker's heavy-job queue is full; Retry-After: 5 |
| 503 | tiles_unavailable | Routing tiles could not be read |
A loop the work budget cut short is still answered when one was found (search.stopped says so); with none, the reason names the limit, never "no loop exists".
Every request is one heavy job: admission, the shared 25 s and 12 M-node budget, receipts with op: roundtrips, a hard kill 10 s past the deadline.
| Case (3 alternatives unless said) | Time | Tiles |
|---|---|---|
| Zermatt hike 12 km (2 alternatives) | 0.7 s | — |
| Interlaken hike 40 km | 2.5 s | 16 |
| Tokyo run 40 km / hike 40 km | 4.6 s / 4.0 s | 16 |
| London hike 40 km, New York run 40 km | 9.5 s, 10.0 s | 20, 16 |
| Paris bike 60 km, London bike 60 km, Oslo bike 60 km | 12.4 s, 12.9 s, 9.8 s | 42, 36, 64 |
| Over the public limits: Tokyo run 60 km | 24.1 s, at the budget | 25 |
| Over the public limits: Tokyo bike 80 km | 21.7 s | 49 |
| Over the public limits: Interlaken hike 100 km, Oslo bike 70 km, Tromsø hike 60 km | refused: corridor over 64 tiles | — |
Hence 40 km on foot and 60 km by bike: inside about half the budget everywhere measured, and inside the 64-tile corridor up to about 60° north (a 60 km loop from Tromsø would still be refused as corridor_too_large).
Consumers
-
The parity script (here) and
npm run test:roundtrip.
Versioning
Additive fields may appear in roundtrips/1. A change of meaning, a removed field or a new default is roundtrips/2.
JSON Schema
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://trailsplits.com/schemas/roundtrips-1.request.json",
"type": "object",
"additionalProperties": false,
"required": ["start"],
"properties": {
"start": { "type": "array", "items": { "type": "number" } },
"distance_km": { "type": "number" },
"distance_m": { "type": "number" },
"profile": { "enum": ["hike", "run", "bike"] },
"direction": { "type": ["number", "null"] },
"alternatives": { "enum": [0, 1, 2, 3] },
"max_sac": { "enum": [1, 2, 3, 4, 5, 6] },
"avoid_paved": { "type": "boolean" },
"hills": { "type": "number" },
"bicycle_type": { "enum": ["road", "hybrid", "mountain"] },
"strategy": { "enum": ["graph", "ring", "auto"] },
"climb_target": { "type": "object", "additionalProperties": false, "required": ["ascent_m"], "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 } } },
"caller": { "type": "string" }
}
}
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://trailsplits.com/schemas/roundtrips-1.response.json",
"type": "object",
"required": ["schema", "engine", "status", "reason", "request", "loops", "search", "timing"],
"properties": {
"schema": { "const": "roundtrips/1" },
"status": { "enum": ["complete", "rough", "none"] },
"reason": { "type": ["string", "null"] },
"request": { "type": "object", "required": ["start", "target_m", "profile", "direction", "alternatives", "settings", "settings_defaulted"] },
"loops": {
"type": "array",
"items": {
"type": "object",
"required": ["rank", "status", "distance_m", "target_m", "target_error_pct", "repeated_m", "repeated_share", "stem_m", "spur_m", "turn_points", "bearing_deg", "quality", "shape", "ascent_m", "descent_m", "ascent_method", "time", "surfaces", "hazards", "ways", "difficulty", "warnings", "unknowns"],
"properties": {
"status": { "enum": ["complete", "rough"] },
"engine": { "enum": ["graph", "ring"] },
"second_pass_share": { "type": "number", "minimum": 0, "maximum": 1 },
"score": { "type": "object", "required": ["length_fit", "clean", "marked", "total"] },
"climb_target": { "type": "object", "required": ["heights", "largest_ascent", "dimensions", "met", "summary"], "properties": { "heights": { "enum": ["terrain", "graph"] }, "met": { "type": "boolean" } } },
"quality": { "type": ["number", "null"] },
"shape": { "type": "string" },
"time": { "type": ["object", "null"], "required": ["model", "minutes", "moving_only", "applies", "calibration", "outside_calibration", "reasons", "models"] },
"surfaces": { "type": "object", "required": ["paved_m", "gravel_m", "trail_m", "unknown_m", "mapped_m", "class_default_m", "stretches"] },
"ways": { "type": "object", "required": ["by_type_m", "marked_m", "max_sac", "ford_m", "aid_m", "informal_m", "steps_m"] },
"difficulty": { "type": ["object", "null"], "required": ["scale", "graded_m", "untagged_path_m", "road_m", "hardest"] },
"warnings": { "type": "array", "items": { "type": "object", "required": ["code", "message"] } },
"unknowns": { "type": "array", "items": { "type": "object", "required": ["code", "message"] } }
}
}
},
"search": { "type": "object", "required": ["version", "tree_nodes", "candidates", "pairs_routed"] },
"timing": { "type": "object" }
}
}
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://trailsplits.com/schemas/roundtrips-1.error.json",
"type": "object",
"required": ["error"],
"properties": { "error": { "type": "object", "required": ["code", "message"], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } }
}