Route between two points

Give the two ends as from_lat/from_lon and to_lat/to_lon, or as
from/to — each a {"lat", "lon"} dict, a GERS id, or a free-text place
name — but not both (and not neither); either way returns
{"error": "bad_request"} naming the choice. Do not call geocode(),
resolve_place(), or geocode_batch() first: names and ids resolve in
parallel inside this call, and the "from"/"to" blocks come back
carrying whatever each end resolved to.

Compact directions, not turn-by-turn: builds a street graph from
Overture's transportation theme around the two points and returns

Each mode has a straight-line-distance cap on the two points, rejected
before any graph is built (see routing.ROUTE_MAX_STRAIGHT_LINE_M, derived
per-mode from the shared graph-extraction radius cap — roughly
walk 7.5km, cycle 23.5km, drive 95.5km) — real road distance only ever
exceeds straight-line, so anything past the cap can't produce a route
worth extracting for anyway; returns {"error": "route_too_long"} with
the exact cap in "max_distance_m". An unrecognized mode string returns
{"error": "unsupported_mode"}; non-finite or out-of-range coordinates
(lat outside [-90, 90], lon outside [-180, 180]) return
{"error": "bad_request"}. If no usable graph or street node is found
near either point, returns {"error": "no_graph_nearby"}. If both points
snap into the graph but no path connects them (e.g. disconnected
islands of road data), returns {"error": "no_route", "try": ...}
rather than raising — "try" is a mode-tuned next move (roadmap §4). If
the extraction graph hit its internal size cap, the result
carries "truncated": true — the route may be suboptimal or incomplete.

include_path=true adds "path", a GeoJSON LineString from the origin's
snapped node to the destination's that follows the streets' own
geometry (curves included), simplified to fit the token budget, with
"path_max_deviation_m" bounding how far it strays from the exact
street path. Off by default (the polyline dwarfs the rest of the
answer) — ask for it only to draw or trace the route. If even a fully
simplified line won't fit, you get "path_omitted": true instead of a
line that stops short of the destination.

include_elevation=true adds "elevation": a compact climb profile from
the same keyless Copernicus GLO-30 DEM reader as point elevation lookups
use, sampled along the route —
"total_climb_m", "total_descent_m", "max_grade_pct", and a small
"samples" array of [distance_along_m, elevation_m] points, thinned to
fit the token budget. Off by default. Where the DEM has no coverage
along part or all of the route, the affected numbers are never faked as
0.0 — you get a "note" saying so instead (and no climb/descent/grade
keys at all if there's no coverage anywhere on the route). If even the
note-only form can't fit the budget, you get "elevation_omitted": true.

prefer="flat" asks the router to trade distance for climb — steeper
detours cost more than gentler ones, so a longer-but-gentler path can
win over a shorter-but-steeper one. Only meaningful for mode="walk" or
"cycle" (returns {"error": "bad_request"} for mode="drive"); needs
per-node elevations for the extracted street graph, fetched from the
same Copernicus source (bounded — see routing.FLAT_MAX_ELEVATION_NODES),
so if that data isn't reachable or has no coverage here, the route falls
back to plain-distance routing and says so in "prefer_note" rather than
silently ignoring the preference. IMPORTANT: prefer="flat" minimizes
elevation grade only — it is NOT a step-free, stroller-, or
wheelchair-accessible mode. Overture's transportation data (as read
here) carries no step-count, kerb-ramp, or surface attributes, so a
flight of stairs classified as ordinary walkway geometry can still
appear on a "flat" route if it's short and roughly level. Don't offer
this as an accessibility guarantee to the user; it isn't one.

avoid=["motorway"] (and/or "trunk") is the "no highways" ask: those
classes and their on/off ramps are dropped from the street graph before
the search, and the answer echoes "avoid". Those two values are the
whole vocabulary — anything else is a bad_request listing them. There is
no toll or ferry option, deliberately: Overture's road data carries no
toll attribute at all, and this graph is road-only so ferries are never
routed over. Tell the user that rather than approximating either with
avoid=["motorway"]. On walk and cycle it is a no-op (both already
exclude those classes) and says so in "avoid_note" instead of erroring.
An avoiding route is a different graph, so the first one in an area can
need its own confirm even where a plain route is warm; if the avoided
roads were the only link, the usual no_route comes back with "try"
naming avoid.

confirm=true after the user agreed to wait for a first-time street-graph
build (about 5–25 seconds). Pass it only after a needs_confirm reply
and they said yes. A warm or cached graph never needs it.
Omit confirm unless you just asked and they said yes.

A from/to name matching several equally-ranked places returns
{"error": "ambiguous_place", "candidates": [...]} instead of picking a
city; an unresolvable name or id returns {"error": "not_found"}; a
malformed one (empty string, dict missing lat/lon, wrong type) returns
{"error": "bad_request"} — the offending side is named in "field".
Ends that resolve a city apart return {"error": "too_far"} with both
ends and the mode cap, before any graph is built. from_to is this same
routing with a walk default.