About

LiveMap Routing is a Dropwizard-hosted GraphHopper plugin with three pedestrian product profiles (Fast / Calm / Safe) and a custom lm_* edge-attribute contract. The facade speaks POST /api/v1/routing/route; profile weights are inspectable on /profiles.

The routing contract

Product profiles — foot_fast, foot_calm, foot_safe. Catalog at GET /api/v1/routing/profiles.
Time buckets — six slices (wd_am, wd_pm, wd_nt, we_am, we_pm, we_nt) plus auto (Zurich wall-clock).
Edge attributes — five lm_* dimensions: lm_tree_density, lm_lamps, lm_accident, lm_crime, lm_presence. Pipeline-owned; documented in the data-pipeline repo.
Status semantics — no-route is a route-domain 200 with status: "no_route" + routeErrors; 400 is reserved for invalid bodies, profiles, or buckets; 500 for misconfiguration. (Decision-log 2026-04-29.)

The routing engine

GraphHopper first finds a path through the street graph, then walks that path edge-by-edge to decide where a person needs a useful instruction. An instruction's interval in the response points array marks where the instruction starts in the geometry; the anchor index is what /map and /field-review snap markers to.

The five stages:

Snap — user coordinates match the nearest usable edge.
Query graph — snapped points become temporary nodes so routing can start mid-edge.
Leg routing — one path per leg, then concatenated.
Walk for guidance — every edge transition is inspected; an instruction is emitted only when the transition is likely to matter.
Attach anchors — instructions get intervals against the final geometry.

Custom lm_* weights are applied request-time via custom_model — the foot_safety base profile encodes only access + speed; weights live on /profiles. (Decision-log 2026-04-09: foot_safety profile vs request custom_model.)

Guidance research highlights

Tone and phrasing of pedestrian instructions differ from driving guidance — testers consistently prefer concise direction-of-travel cues over named-street prompts in dense Old-Town segments.
Anchor placement at intersection entry beats placement at intersection center for decision-point recall.
Mode-aware language ("through the park", "via the back street") aligns the route with the mode in walker perception even when the geometry alone could go either way.

Future cycles will measure these against walked annotations on golden routes.

Reference

Service config: runtime/config-livemap.yml; per-profile weights: runtime/foot_safety.json.
OpenAPI: service/src/main/resources/openapi/livemap-routing-openapi.json.
Decision log: decision-log.md — covers profile evolution, encoded values, deprecated challenger flow, golden-routes reorg (2026-06-16).