Compare walk / cycle / drive
compare_modesRead-onlyIdempotent
Walk vs cycle vs drive between two places, in one call.
Instructions
Walk vs cycle vs drive between two places, in one call.
"Should I walk, bike or drive from A to B?" is three route() calls;
this is one. The ends resolve exactly once and every mode routes
between the same two coordinates, so the rows are comparable. Use it
when the user is choosing a mode; when the mode is already known,
route() or from_to() gives the fuller answer (export maps/gpx/text,
optional polyline).
Pass each of from/to as a free-text place name, a {"lat", "lon"} dict,
or a GERS id — mixed freely, exactly as from_to takes them.
Do not call geocode(), resolve_place(), or geocode_batch() first. modes
is an optional subset of ["walk", "cycle", "drive"]; omitted means all three
in that order (stored mode preferences are not consulted — every mode
asked for is computed). A mode outside that vocabulary, or an empty
list, returns {"error": "bad_request"}; duplicates collapse, order kept.
Returns {"from", "to", "modes", "fastest", "shortest", "summary"}.
"from"/"to" carry what each end resolved to (name/id when the input was
a name or GERS id, lat/lon always). "modes" is one compact row per
requested mode, in the requested order: {"mode", "distance_m",
"duration_s", "duration_min"} — no path, no export, no per-row
endpoints; with include_elevation=true a row also carries
"total_climb_m"/"total_descent_m" where the DEM covered the route
(never faked as 0). "fastest"/"shortest" name the mode with the lowest
duration/distance among the rows that routed, or null if none did.
"summary" is a short deterministic sentence or two built from the rows.
A mode that cannot be routed fails inline in its own row — {"mode",
"error", "detail"} — and never aborts the call: "too_far" when the ends
exceed that mode's straight-line cap (walk ~7.5 km, cycle ~23.5 km,
drive ~95.5 km — so a cross-town pair often gives a drive row and a
too_far walk row), "needs_confirm" with its eta/eta_s when that mode's
street graph is cold and confirm is false, or whatever error route()
returned (no_graph_nearby, no_route, ...). Only end resolution fails
the whole call: {"error": "ambiguous_place" | "not_found" |
"bad_request"} with "field": "from" | "to", as from_to does.
Same cost model as route(): walk 1.4 m/s, cycle 4.2 m/s, drive from
posted speed limits or a class default — a posted-speed model with no
live traffic, which the summary says whenever drive routed.
confirm=true after the user agreed to wait for a first-time street-graph
build (about 5–25 seconds per cold mode — each mode is its own graph).
Pass it only after a needs_confirm row and they said yes. A warm or
cached graph never needs it. Omit confirm unless you just asked and
they said yes.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| to | Yes | ||
| from | Yes | ||
| modes | No | Modes to compare, in answer order. Default: walk, cycle, drive. | |
| confirm | No | ||
| include_elevation | No |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
No arguments | |||