How GraphHopper turns a route into guidance

The routing engine first finds a path through the street graph. Guidance is added afterward by walking that path edge by edge and deciding where a person needs a useful instruction. The instruction anchor is the point in the returned route geometry where that instruction starts.

High-level picture

A/Brequested points, snapped to the graph

turninstruction anchor chosen from edge transitions

viazero-length waypoint instruction between route legs

The five stages

1

Snap the requested points

User coordinates are matched to the nearest usable graph edge. Profile access, heading, point hints, and snap-prevention rules can change which edge is accepted.

2

Build a query graph

Snapped positions become temporary graph nodes, so routing can start and finish exactly on the matched street rather than only at permanent OSM nodes.

3

Calculate route legs

For a route with multiple points, GraphHopper calculates one path per leg: point 0 to 1, point 1 to 2, and so on.

4

Walk the edges for guidance

The engine visits each edge transition and emits an instruction only when the transition is likely to matter: turn, fork, roundabout, ferry, u-turn, via, or finish.

5

Attach anchors to geometry

Every instruction gets an interval in the final points array. The interval start is the guidance anchor shown to clients.

What an anchor is in the API response

GraphHopper returns one shared route polyline and a list of instructions. Each instruction contains an interval with two point indices. The first index is where that instruction starts; the second index is where the next instruction starts.

{
  "points": "encoded route geometry...",
  "instructions": [
    {
      "text": "Continue onto Bahnhofstrasse",
      "sign": 0,
      "interval": [0, 8]
    },
    {
      "text": "Turn right onto Uraniastrasse",
      "sign": 2,
      "interval": [8, 15]
    }
  ]
}

In this example, point 8 is the anchor for the right-turn instruction.

Why every junction does not become an instruction

Only one legal continuation	Usually no instruction. If there is no real choice, telling the user to turn often adds noise.
Road bends but keeps the same name	Often suppressed, especially when alternatives are much slower or look like side roads.
Two roads continue almost straight	Can become `keep left` or `keep right`, because the route choice is visually ambiguous.
Roundabout	Creates a roundabout instruction and counts exits by inspecting outgoing non-roundabout edges.
Via point	A non-final leg finish is converted into a `Reached waypoint` instruction. It can be hidden with `via_point_instructions=false`.

Technical reference

`ViaRouting.lookup`	Snaps input points to graph edges with heading, hint, and access filters.
`QueryGraph.create`	Creates temporary nodes/edges for snapped positions.
`Path.calcPoints`	Builds the route geometry from edge pillar points and adjacent nodes.
`InstructionsFromEdges`	Classifies edge transitions into turn signs or ignores them as noise.
`PathMerger`	Merges route legs, replaces intermediate finishes with via instructions, and updates context.
`PathSimplification`	Simplifies the polyline without removing waypoint or instruction-boundary anchors.
`InstructionListSerializer`	Serializes instruction intervals into the JSON response.

LiveMap takeaway

The route shape and the guidance list are separate products of the same edge path. LiveMap can use the full geometry for drawing and the instruction intervals for explaining where the next decision point starts. A cleaner instruction list does not require a different route; it usually means tuning the instruction-generation heuristics or response flags.

Open route map Inspect profiles