Routing Tool
:::caution Last revised 2026-05-09 — not re-verified
This page has not been checked against the running system since it was
written, and predates a large part of the current product. It is scheduled
for rewrite. For anything about the API, /docs on a running server is
authoritative.
:::
The Routing Tool adds turn-by-turn navigation, route simulation, speed camera alerts, nearby POI search, address geocoding, basemap switching, route saving, and real-time location sharing — all powered by the open-source Valhalla routing engine.
A companion Loop Route Generator lets you compute circular routes that start and end at the same point, with a preferred compass direction and target distance.
Opening the tool
Click the routing toolbar button (two circles connected by a curved line) to open the Routing panel in the left sidebar.
Setting waypoints
Address search (geocoder)
Type any address or place name into the search bar at the top of the routing panel. Results are fetched from the Photon/OSM geocoder. Click a result to fly to it on the map, then use the action chips below the search bar to assign it:
| Chip | Effect |
|---|---|
| Set Start | Use as the route start point |
| Set End | Use as the route end point |
| Add Waypoint | Insert as an intermediate stop |
| Fly to | Just fly the camera there — no waypoint added |
Map click
With the routing panel open, click directly on the Cesium globe to pick start, end, or waypoint positions. The active pick target is shown in the panel header.
Waypoint list
Intermediate waypoints appear in a list below the start/end displays. Each row has a ✕ button to remove that stop. Drag the ⠿ handle to reorder waypoints.
Route options
Expand the Options section to configure:
| Option | Description |
|---|---|
| Costing | Travel mode: motorcycle (default), auto, bicycle, pedestrian, truck… |
| Units | km or miles |
| Alternates | 0–3 alternative routes shown as dimmed lines |
| Avoid tolls / highways / ferries | Toggle per route |
| Top speed | Cap vehicle speed for time estimation |
Computing a route
With at least a start and end point set, click Get Route. The route line appears on the map in teal. The result panel shows total distance and duration.
If alternate routes were requested, click any alternate line to promote it to the primary route.
Route simulation
After a route is computed, the Simulate button starts a virtual drive along the route:
- A vehicle marker follows the route at configurable playback speed
- Turn instructions update in the panel as maneuvers approach
- The camera follows the vehicle automatically (configurable below)
Simulation controls
| Control | Description |
|---|---|
| Speed slider | Playback speed multiplier (1× to 20×) |
| ▶ / ⏸ | Play / pause |
| ⏹ | Stop and reset |
| ↺ Recenter | Snap the camera overhead above the vehicle |
Smart camera (follow mode)
The camera stays behind the vehicle and tilts to show the road ahead. Three sliders in the Camera section control the view:
| Slider | Description |
|---|---|
| Min altitude | Lowest camera height (metres) |
| Max altitude | Highest camera height (metres) |
| Back offset | How far behind the vehicle the camera sits |
Each slider has a ceiling input (the small number field to its right) to set the slider's maximum range.
Clicking ↺ Recenter during simulation switches to a top-down overhead view at 2 000 m, showing roughly a 1 km² area around the vehicle.
Speed camera alerts
Speed camera locations are fetched automatically from OpenStreetMap when a route is computed. Cameras appear as red SVG pins on the map.
A yellow ⚠ Speed camera ahead banner appears in the simulation panel when the vehicle comes within 300 m of a camera. The banner clears once the camera is passed.
Camera data is cached in Redis per 1°×1° grid cell. Once a day the server copies every camera our own Overpass mirrors hold into that cache, so even a route across Europe gets its cameras at once (Bergen → Romagnano: 231 cells, answered from the cache instead of 107 s of lookups). A cell the cache does not hold yet is looked up when a route needs it and kept for 24 hours.
Live traffic incidents
Tick 🚧 Show traffic incidents under the route options to draw live road status for the route's area: closures, roadworks, queues and accidents, pulled from the national road authorities.
Incidents are coloured by how much they will cost you:
| Colour | Severity | Means |
|---|---|---|
| Red | Blocking | The road is closed |
| Orange | Major | A carriageway or several lanes are shut |
| Amber | Minor | One lane, alternating traffic, temporary lights |
| Blue | Info | Reduced limit, narrowed lanes, and similar |
Click a line or pin for the details: the road, the authority's own wording, the English, the validity window, any expected delay, and whether a detour is signposted.
The authority's own text is always shown. Underneath it you get either a translation, where that authority's licence allows one, or a summary built from their status codes where it does not — the popup labels which, so you can tell a translated sentence from a generated one. Norwegian text is never translated: their terms forbid it.
An attribution line appears under the toggle whenever incidents are on screen. It is a condition of use for these feeds, not decoration.
This does not yet change your route. Phase 1 draws incidents; routing around closures comes later. If the overlay is empty, check that the source is alive — a road authority's feed being down shows as no incidents rather than as an error.
Nearby POI search
Click the search+ toolbar button to open the Nearby POI Search panel.
- Category — choose from Gas Station, Camping, Grocery, Restaurant, Parking, Hotel, Hospital, Pharmacy
- Origin — where to centre the search:
- Route start — uses the set start point
- Route end — uses the set end point
- Map center — uses the current Cesium camera position
- Radius (km) — search radius, 1–100 km (default 20)
- Click Search
Results appear as coloured emoji pins on the map and as a list below. Each result has a ＋ WP button that adds it as a route waypoint.
POI data is cached in Redis for 6 hours per category/location/radius bucket.
Route Manager
Click the list toolbar button to open the Route Manager panel.
Saving a route
After computing a route, enter a name (and optional description) in the Route Manager panel and click Save current route. Routes are stored in PostGIS and are private to your account.
Route Manager requires a PostgreSQL/PostGIS database. If
POSTGRES_HOSTis not configured the panel is still visible but save/load will return an error.
Loading a route
Saved routes appear in the list. Click a route card to load it — the waypoints and route line are restored exactly as saved.
Exporting a route
Each route card has two export buttons:
| Format | Description |
|---|---|
| GPX | Standard GPS exchange format, compatible with Garmin, OsmAnd, etc. |
| GeoJSON | LineString geometry, importable into QGIS, Mapbox, etc. |
Basemap selector
Click the globe toolbar button to open the Basemap panel:
| Basemap | Description |
|---|---|
| FastGIS Adventure | Our own basemap, the one the phone and the desktop draw, rendered as raster for the globe (default; see the developer page on the raster basemap). Outside Europe the globe shows Natural Earth. |
| ESRI World Imagery | Satellite imagery |
| Custom | Any XYZ tile URL of your own ({z}/{x}/{y}), saved on this browser |
The selected basemap persists across browser sessions via localStorage.
Location sharing
Click the person+pin toolbar button to open the Location Sharing panel.
- Enter a Group ID — any shared string, e.g.
trip-norway-2025 - Enter Your name — identifies you to other group members
- Click Start sharing
Your position is published every 10 seconds. Other group members appear as labelled pins on the map with their initials in a deterministic colour. The member list shows each person's age (seconds since last update) and speed.
Click Fly on any member row to jump the camera to their location.
Positions expire automatically after 5 minutes of inactivity.
Loop Route Generator
Click the circular-arrow toolbar button to open the Loop Route Generator panel.
The loop route tool generates a circular route — a ride that starts and ends at the same point — of about the distance you ask for, leaving in your chosen direction.
Parameters
| Parameter | Description |
|---|---|
| Start from | Map centre (default) uses the current Cesium camera centre; GPS location uses the device fix when available |
| Distance (km) | Target total route length, 10–2 000 km |
| Direction | Preferred outbound heading: N, NE, E, SE, S, SW, W, NW |
| Placement | Edge (default): the start lies on the loop and the loop bulges toward the direction. Center: the loop goes around the start. |
| Waypoints | Number of points placed around the loop (2–8, default 6). More waypoints make a rounder loop. |
Toggles in the panel:
| Toggle | Description |
|---|---|
| Avoid backtracking | Marks intermediate waypoints as Valhalla type: "through" — the engine passes through without stopping or U-turning, reducing same-road overlap. |
| Force departure heading | Adds a heading constraint on the start location so the route departs in the requested compass direction (±45°). |
| Curvy roads | Weaves the best curvy road of the area into the loop. |
| Beaches | Weaves the best beach of the area (sea, lake or both) into the loop. |
Routing options (costing model, highway/trail/ferry preference, top speed, etc.) are shared with the main Routing Tool — adjust them there and they apply here too.
How it works
- Waypoints are placed on a ring around (or, with Edge, through) the start, fanned from the chosen direction, and Valhalla routes start → wp1 → … → wpN → start.
- The routed length is measured and the ring is resized until the loop is within 12 % of the distance you asked for, usually in two to four tries.
- Stub detours to a waypoint and stretches ridden out and back (fjord arms, dead-end valleys) are cut, and the loop is extended on the connected side to keep its length.
- Where the ring cannot work (deep valleys), the generator picks a far point on the road network in your direction and comes back by different roads.
- Closed gates and advisory zones on the loop are routed around, as on any route.
The answer says honestly whether the ask was met: loop_status is ok, distance_short, distance_long or degenerate (a loop that rides the same roads out and back), with the share ridden twice (dangle_fraction).
Two or three loops (API)
POST /grass/routing/circular with loop_options 2 or 3 returns more than one loop. The first is the loop for the asked direction, exactly as without the field. The others ride the neighbouring headings (±45°) and are generated side by side. Each option carries its own trip, verdict, figures (km, time, distance error, % ridden twice, % unpaved, climb) and badges:
| Badge | Given to | Only when |
|---|---|---|
best_match | the loop with a clean verdict closest to the asked km | it is at least 2 points closer than the next clean loop |
most_unpaved | the loop with the highest unpaved share | it is at least 5 points ahead |
least_ridden_twice | the loop that rides the fewest roads twice | it is at least 5 points ahead |
most_climbing | the loop with the most climb (terrain model) | it climbs at least 10 % and 100 m more |
A loop that shares more than 60 % of its roads with an earlier option, finds no loop, or is not done within 10 s is left out and listed in options_dropped with the reason. Without loop_options the answer still carries options, holding only the loop itself, and costs nothing extra.
After computing
- The status line shows the actual distance and estimated duration.
- Click ↗ Add to Route to send all waypoints to the main Routing Tool (where you can inspect turn-by-turn instructions, simulate the ride, or adjust individual stops).
- Click 🔖 Save to persist the loop to your Route Manager account.
Tile coverage (adding countries)
By default Valhalla is built with Norwegian OSM data. To route through additional countries (e.g. for a Norway → Italy trip):
- Edit
valhalla-tiles.confon the server — uncomment the countries you need - Run the rebuild script:
./scripts/valhalla-rebuild.sh
The script downloads and builds tiles for all active regions (Norway → Italy requires Sweden, Denmark, Germany, Austria, Italy — roughly 45–90 min build time), then prints the command to lock the tiles in for future restarts.