Nine documented endpoints
plan, scenic, optimize, by-feature, difficulty, water-sources, resupply, elevation, health.
Technology · Engine · Whitepaper
Nine endpoints. One documented classifier.
The routing service composes OSRM, Valhalla and Overpass behind nine endpoints, applies a constraint solver, and classifies difficulty against published thresholds. This page documents the endpoints, the constraint vocabulary and the thresholds, so a result can be reproduced rather than trusted.
01 / Problem statement
What this has to solve.
Outdoor routing is not car routing with different tiles.
The cost function is not time. A hiker optimizing for elevation gain, a paddler optimizing for current, and a loaded truck optimizing for maximum grade are three different objective functions over the same geometry.
The network is incomplete and heterogeneous. Trails, forest roads, waterways and open ground exist at different data qualities and sometimes not at all.
The answer needs enrichment to be usable. A line with no water sources, no resupply, no difficulty class and no coverage forecast is a geometry, not a plan.
02 / Mechanism
The design, component by component.
- Mode dispatch
- The travel mode selects the engine. Road goes to OSRM with the multi-level Dijkstra algorithm. Multi-modal, elevation-aware and surface-aware requests go to Valhalla. Trails go to a dedicated trail graph.
- Constraint vocabulary
- max_distance_km, max_elevation_gain_m, scenic_preference, past_water and preferred_surface are solver inputs. A constraint that cannot be satisfied is reported as unsatisfiable rather than silently relaxed.
- Feature enrichment
- Overpass queries retrieve rivers, lakes, waterfalls and viewpoints for scenic routing, and water sources and resupply points for the corridor.
- Difficulty classification
- Published thresholds over distance, elevation gain and maximum grade. The same classifier is used everywhere in the product, so a difficulty shown on an activity page and one shown on a route agree.
- Elevation profile
- Per-segment gain, loss and maximum grade, which is the evidence behind the difficulty class.
- Coverage forecast
- The finished geometry is evaluated by the terrain-occlusion signal predictor to mark where coverage ends.
- Offline recomputation
- A route can be re-solved on the device against the cached graph, so losing signal does not mean losing the router.
03 / Properties
What this guarantees.
Explicit unsatisfiability
A constraint that cannot be met is reported, not relaxed.
One difficulty classifier
Shared across the whole product.
Reproducible results
Same inputs, same engine, same answer.
Configurable upstreams
OSRM, Valhalla and Overpass base URLs are deployment parameters, including self-hosted.
On-device re-solve
Against the cached graph.
04 / Reference
| Level | Max distance | Max elevation gain | Max grade |
|---|---|---|---|
| Easy | < 8 km | < 300 m | < 10% |
| Moderate | < 16 km | < 800 m | < 15% |
| Hard | < 32 km | < 1600 m | < 25% |
| Expert | ≥ 32 km | ≥ 1600 m | ≥ 25% |
05 / Process
Traced, node by node.
Reproducible, not magical.
Self-host the upstreams if you need determinism you control.