stages-huts/1: multi-day guides, their stages, transport, stays and huts (read only)
GET · POST · PATCH · DELETE https://api.trailsplits.com/v1
Create projects, issue and rotate keys, and read usage. Sign-in uses your TrailSplits account; the API console is built on these calls.
Contract
Operations
Both are GET on trailsplits.com (the site app). They answer JSON with Access-Control-Allow-Origin: * and Cache-Control: public, max-age=300, s-maxage=3600. The files change only with a deploy.
GET /api/guides/v1/guides[?country=CH]
GET /api/guides/v1/guides/{id}
| Parameter | Meaning |
|---|---|
country | ISO 3166-1 alpha-2: the country the guide is filed under (a cross-border trail is filed under one) |
id | The guide's slug, as in /trails/{id} |
The list
{ schema, count, guides: [...], notice }. Each entry has these fields:
-
id,name,country,country_name,page_url; -
distance_kmandascent_mfor the whole route; -
stage_count; -
curated_stays: whether the guide has reviewed stays, or only the huts OpenStreetMap maps.
The record
| Field | Meaning |
|---|---|
schema | stages-huts/1 |
id, name, page_url | The guide |
country, country_name | ISO code and name of the country it is filed under |
distance_km, ascent_m, descent_m | The whole route as the guide page gives it; climb and descent are the sums of the stages' |
stage_basis | How the stages were cut: official, source-aligned, planning or transit-optimized |
route_source | The route's official name and page, and when the mapped line was checked against it |
route_trust | scope (complete, partial, segmented, unverified), navigation_status (verified, review_required, disabled) and the review note. A line that is unverified or disabled is not for navigation |
season | The guide's best months and snow-risk months, as it writes them, with its note |
stages[] | In walking order (below) |
places[] | Every curated place of the guide (below); empty when the guide has none |
places_retrieved_on | When the place file was last read against the operators |
notices[] | The official notice pages the guide watches: label, url, checked_on (the oldest review behind the label), changed_on |
unknowns[] | Below |
A stage:
| Field | Meaning |
|---|---|
former_ids | Only on a stage that had other ids before: its earlier ids, oldest renames included (a renamed or re-cut stage; the old page addresses redirect to this stage). A stage id you stored that is no longer a current id is found here. Added 13 Oct 2026, after 63 automatic stages were renamed on 12 Oct to end at real places |
distance_km | The length of the stage's mapped line, as its page shows it |
transfers[] | The boats and rides on the stage, from the curated legs: mode (boat, ride), how ("bus and boat"), km (a boat's), minutes (a ride's), text |
detour | Where an authority has closed part of the stage every day and signs a detour (Tour Monte Rosa stage 9 by Täsch): km, minutes, ascent_m, descent_m and source_url as the operator states them. The line stays the mapped route. Null otherwise |
ascent_m, descent_m | The stage page's climb and descent: the operator's where it publishes a stage table (climb_basis: official), else measured on the mapped line (measured), else the guide's (guide) |
estimate_s | Our estimate, seconds: the measured time, else the guide's. Never the operator's; the day planner compares the two |
official | What the operator states for exactly this stage: minutes, stated_time, and km, ascent_m, descent_m where the guide carries the official stage table (GR 249), with source_url (the time's page) and climb_source_url (the stage table's page, when the climb comes from another page). Official climb tables: GR 249, Alta Via 1 (Cortina) and the Tour Monte Rosa (tmr-matterhorn.ch), for legs that are exactly an official stage. Null otherwise |
guide | The guide's own ascent_m, descent_m and time_s, which the pages no longer quote |
start, end | name, and transit: the stop or station that serves that end (name, kind, lat, lon, distance_m, walk_minutes), or null |
stops[] | Public-transport stops on the stage: name, kind, lat, lon, km along the stage |
stays | Curated stages only, else null. start and end are place ids. nearby maps a pass, lake or town end to the places that offer the bed. meal_stops lists huts that serve food, not beds. stated_times[] are the operators' or authorities' own times for this leg, in either direction, each with its source. minutes is null when the source states no time for the leg; the row's note then says what it does state. closures[] are what an authority has closed on the stage, by km (from_km, to_km), with the dates (on, every day when absent) and the source. state is closed, intermittent (closed at times), unconfirmed (an order covers the area; the trail's exemption is not published) or diverted (added 13 Oct 2026): the stretch is closed but walkable by an official signed diversion (the Cotswold Way's A417 diversion by Birdlip). A diverted closure may carry extra_minutes and extra_km, the diversion's extra time and distance as the operator publishes them; each is absent when not published. The day planner adds them to the day that walks most of the stretch and never treats it as a closed day. This differs from detour: detour is a whole stage walked on an official detour, with the detour's own km, minutes, ascent and descent replacing the stage's figures, while diverted covers a stretch of a stage and adds its extra on top of the stage's figures |
huts_along | On guides without curated stays: the huts OpenStreetMap maps within 300 m of the stage line (built_on, source: openstreetmap, huts[] with km and distance_m). This is evidence that a building is there, not that it has a bed or is open |
A place is the curated record with its keys in snake_case. Every fact read outside OpenStreetMap carries a source with url, retrieved_on and an optional note. The main fields:
-
id: the OSM element,osm:n123; -
name,kind(staffed_hut,refuge,bivouac,hotel,hostel,pass,lake_trailhead,town,camp),lat,lon,ele; -
operator,website,phone,email; -
reservation:mode(online,request,email,none,unknown),url,note, andopens(a dated booking opening); -
seasons[]:year,from,to,status(published,partial,unpublished,closed),off_season; -
closed_on[],services(beds, meals, winter room),notices[],transport[],stay_nearby.
A missing field is not published by the operator. It is never guessed.
Unknowns
| Code | Meaning |
|---|---|
stage_time_is_guide_estimate | At least one stage quotes the guide's own time (no operator's time and no current measurement) |
times_run_optimistic | At least one stage's time is measured outside Switzerland, where the model runs short of operators' times |
line_figures_not_route_analysis | No stage of the guide has a current line_analysis |
line_analysis_partial | Some stages have a current line_analysis, others not (a line changed since the last batch) |
stays_not_curated | The guide has no reviewed stays: places is empty, and stages carry at most huts_along |
huts_along_are_osm_only | At least one stage lists OpenStreetMap huts, which are not checked against an operator |
route_unverified | The mapped line is unverified or disabled for navigation |
country_unrecognised | The filing country has no ISO code; country is null |
Errors
| Status | Code | When |
|---|---|---|
| 400 | bad_country | country is not two letters |
| 404 | not_found | No published guide with this id |
Rules
- The page's figures, the page's stays. A stage's figures are those of its page. The stage page reads its stays and huts back from this record, and the test checks that they are identical to the place files' own reading for every curated stage.
-
Never guessed. A season the operator has not published is
unpublishedwith null dates. A booking channel nobody states isunknown. - Sources are pages. No record links a GPX, KML or document file (the rights review of 5 October 2026).
Related contracts
-
closures/1covers closures in a box and the feed. A guide'snoticesare the official pages it watches. The stage closures instays.closuresare the reviewed ones on the stage itself.