Exits along a route

POST https://api.trailsplits.com/v1/route-exits

Checked by a live probe Key optional · 500 credits a day without one 5 credits per call Heavy: 1 at a time on Free

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.

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-exits' \
  -H "Authorization: Bearer $TRAILSPLITS_API_KEY" \
  -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]]}}'

Sends a real request, with your key or the keyless allowance.

Request body

Field	Type	Description
`gpx`	string	One line as GPX, one part, at most 120 km and 5,000 points. Or geometry, not both.
`geometry`	object	A GeoJSON LineString, [lon, lat].
`pace_factor`	number	Scales the signpost walking times (1.25 = 25 % slower).

Response

Field	Type	Description
`schema`	string: route-exits/1
`engine`	object
`settings`	object	pace_factor, within_minutes (60), sample_every_m, along_every_m.
`settings_defaulted`	array
`input`	object
`method`	object
`along`	array
`exits`	array
`longest_without_exit`	object
`longest_without`	object	The same stretch per kind.
`note`	string
`unknowns`	array

Full response schema (JSON Schema)

{
  "type": "object",
  "properties": {
    "schema": {
      "type": "string",
      "enum": [
        "route-exits/1"
      ]
    },
    "engine": {
      "type": "object"
    },
    "settings": {
      "type": "object",
      "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"
      ]
    },
    "method": {
      "type": "object"
    },
    "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"
        ]
      }
    },
    "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"
        ]
      }
    },
    "longest_without_exit": {
      "type": "object",
      "properties": {
        "within_minutes": {
          "type": "number"
        },
        "kinds": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "stretch": {
          "type": "object",
          "nullable": 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"
      ]
    },
    "longest_without": {
      "type": "object",
      "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"
        ]
      }
    }
  },
  "required": [
    "schema",
    "engine",
    "input",
    "along",
    "exits",
    "longest_without_exit",
    "unknowns"
  ]
}

Errors

400, 413, 422, 503, plus the gateway's 401, 429 and 503 (every error code). A refused request costs no credits.

Contract

Where can I get off this? Along one day's line, the answer gives:

the nearest mapped road, public-transport stop, village and hut, each with its walking time and distance on mapped paths from the line;
each placed in metres along the line;
the longest stretch with no road, stop or village within an hour's walk.

What it is, and what it is not.

A mapped way out, never a safe one. A road may be closed to traffic, a stop keeps a timetable, a hut may be shut, and the path to any of them is only as good as the map. There are no verdicts and no "escape route" claims.
Walking times on mapped paths. The Swiss signpost method (SAC/ÖAV: 4 km/h on the level, 300 m an hour up, 500 m an hour down, the smaller of the two halved and added) is applied to each path segment and multiplied by pace_factor. Breaks are not included.
The ways a walker may use. The answer leaves out paths tagged T5 or harder, via ferratas, ferries and bike-only ways. It also leaves out ground off the map.
A hut is shelter, not a way out. It is listed, but it does not end the longest stretch.

Request

{ "gpx": "<gpx…>" }
{ "geometry": { "type": "LineString", "coordinates": [[lon, lat], …] }, "pace_factor": 1.25 }

Field	Default
`gpx` or `geometry`	one of them	One line (one part), at most 120 km and 5,000 points
`pace_factor`	1	0.5 (twice as fast as the signposts) to 2 (twice as slow)
`caller`		Optional label

Response

Field	Meaning
`schema`	`route-exits/1`
`settings`, `settings_defaulted`	`pace_factor`, `within_minutes` (60), `sample_every_m` (250), `along_every_m` (1,000)
`input`	`format`, `points`, `length_m`
`method`	`time`, `network` and `kinds` in words
`exits[]`	Every exit `along` names, in order along the line. Each has `id`, `kind`, `place_kind` (such as `bus_stop`, `village` or `residential`), `name` as mapped (null for roads), `lon`, `lat` (for a road, where the way out meets it) and `osm_id`. Then `nearest_from_m` and `nearest_to_m` (the stretch it is the nearest of its kind for), and `best_minutes` at `best_at_m`
`longest_without_exit`	`within_minutes`, `kinds` (`road`, `transport`, `settlement`) and `stretch` (`from_m`, `to_m`, `length_m`, or null when there is none)
`longest_without`	The same stretch per kind (`road`, `transport`, `settlement`, `hut`)
`note`	In words: a mapped way out, never a safe one
`unknowns[]`	`code`, `message`. `places_unavailable` means the places index did not answer; roads are still searched. `off_network` means some points are more than 150 m from a walkable way, so their exits are unknown and counted as none
`timing`	`windows`, `settled`, `tiles`

Kinds

Kind	What counts
`road`	A public road: residential, unclassified, tertiary or larger, living streets. Not service ways or tracks, which are often private or closed
`transport`	Bus, tram and train stops and stations, halts, cable-car stations, ferry terminals
`settlement`	Villages, towns and cities
`hut`	Alpine and wilderness huts

Errors

{ "error": { "code", "message" } }.

HTTP	`code`	When
400	`invalid_request`	Not JSON, an unknown field, both or neither of `gpx`/`geometry`, `pace_factor` out of range
400	`invalid_gpx`, `invalid_coordinates`	As for route analysis
405	`method_not_allowed`	Any method but POST (and OPTIONS)
413	`body_too_large`, `too_many_points`	Over 1 MB, or over 5,000 points
422	`too_long`, `several_parts`, `no_line`	Over 120 km, more than one part, or no line of two different points
422	`corridor_too_large`, `budget_exhausted`	The ground is too dense to search in one go, or the job's limit ran out: send the line in pieces
503	`overloaded`, `tiles_unavailable`	The heavy-job queue is full, or the routing tiles did not answer

Versioning

Additive fields may appear in route-exits/1. A change of meaning, such as the kinds, the time method or the hour, is route-exits/2.

Conventions · What a call costs · OpenAPI · Get a key