Skip to content

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}
ParameterMeaning
countryISO 3166-1 alpha-2: the country the guide is filed under (a cross-border trail is filed under one)
idThe 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_km and ascent_m for the whole route;
  • stage_count;
  • curated_stays: whether the guide has reviewed stays, or only the huts OpenStreetMap maps.

The record

FieldMeaning
schemastages-huts/1
id, name, page_urlThe guide
country, country_nameISO code and name of the country it is filed under
distance_km, ascent_m, descent_mThe whole route as the guide page gives it; climb and descent are the sums of the stages'
stage_basisHow the stages were cut: official, source-aligned, planning or transit-optimized
route_sourceThe route's official name and page, and when the mapped line was checked against it
route_trustscope (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
seasonThe 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_onWhen 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:

FieldMeaning
former_idsOnly 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_kmThe 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
detourWhere 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_mThe 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_sOur estimate, seconds: the measured time, else the guide's. Never the operator's; the day planner compares the two
officialWhat 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
guideThe guide's own ascent_m, descent_m and time_s, which the pages no longer quote
start, endname, 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
staysCurated 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_alongOn 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, and opens (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

CodeMeaning
stage_time_is_guide_estimateAt least one stage quotes the guide's own time (no operator's time and no current measurement)
times_run_optimisticAt least one stage's time is measured outside Switzerland, where the model runs short of operators' times
line_figures_not_route_analysisNo stage of the guide has a current line_analysis
line_analysis_partialSome stages have a current line_analysis, others not (a line changed since the last batch)
stays_not_curatedThe guide has no reviewed stays: places is empty, and stages carry at most huts_along
huts_along_are_osm_onlyAt least one stage lists OpenStreetMap huts, which are not checked against an operator
route_unverifiedThe mapped line is unverified or disabled for navigation
country_unrecognisedThe filing country has no ISO code; country is null

Errors

StatusCodeWhen
400bad_countrycountry is not two letters
404not_foundNo published guide with this id

Rules

  1. 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.
  2. Never guessed. A season the operator has not published is unpublished with null dates. A booking channel nobody states is unknown.
  3. Sources are pages. No record links a GPX, KML or document file (the rights review of 5 October 2026).
  • closures/1 covers closures in a box and the feed. A guide's notices are the official pages it watches. The stage closures in stays.closures are the reviewed ones on the stage itself.