Example prompts
- “Get me walking directions from Kings Cross to Tower Bridge”
- “How do I drive from Heathrow to Cambridge avoiding tolls?”
- “Plan a cycling route from Greenwich to Richmond Park that avoids hills”
- “What’s the flattest walking route between these two coordinates?”
What you get back
A full route with distance, duration, and turn-by-turn steps. Terrain analytics include total ascent/descent, elevation profile, grade percentages, and a difficulty classification (flat, rolling, hilly, or mountainous). Route flags (has_toll, has_highway, has_ferry) tell you if the route uses any of those — and are omitted entirely when none apply (the common case in urban routing). Only the truthy entries are emitted, so absence of a flag means it doesn’t apply.
Each step carries instruction, distance_meters, duration_seconds, travel_mode, type, and streets. The streets array lists the named roads the step traverses; it’s omitted on unnamed manoeuvres (forks, “destination on the left”, some roundabout exits) so absence means “no street name to attach”, not an empty list. Step-level ferry/toll/highway flags are emitted only when true.
Step type values
type is one of a fixed set of manoeuvre kinds. Grouped by category:
| Category | Values |
|---|---|
| Start / end | start, start_left, start_right, destination, destination_left, destination_right |
| Direction | left, right, slight_left, slight_right, sharp_left, sharp_right, u_turn_left, u_turn_right |
| Continuation | continue, becomes, stay_straight, stay_left, stay_right |
| Highway | merge, merge_left, merge_right, ramp_straight, ramp_left, ramp_right, exit_left, exit_right |
| Roundabout | roundabout_enter, roundabout_exit |
| Ferry | ferry_enter, ferry_exit |
| Fallback | none, unknown |
auto, pedestrian, bicycle, bus, or truck route will produce. The none and unknown values are present for completeness and shouldn’t appear in normal output.
All numeric distance / duration fields are always in meters / seconds regardless of the request units (which only affects the natural-language narrative summary). Pass narrative: true for an AI-generated plain-English summary of the route — the response then also includes a narrative_units field telling you which units the summary was rendered in (kilometers or miles).
For 2-waypoint routes, the route’s totals/terrain/flags are reported once at the top level — the single leg only carries steps. Multi-waypoint routes (3+ waypoints) keep the per-leg breakdown so you can see distance/terrain per segment. Geometry for the route lives in the render envelope as a GeoJSON linestring layer.
Alternate routes: alternates
Set alternates: 1-3 to request alternative routings. When found, the response carries an alternates array of full route objects (same shape as route), each with their own distance, duration, terrain analytics, and turn-by-turn steps. The LLM can reason about “which is flatter?” or “which avoids the highway?” by comparing them.
Alternates aren’t always available — for short urban routes there often isn’t a meaningfully different option. The alternates field is omitted when none are available.
Map rendering
Responses include arender envelope with a linestring layer for the route. Pass compact: true for summary-only responses. See response defaults & controls and render envelopes.