Named-place route
from_toRead-onlyIdempotent
Find the shortest walking, cycling, or driving route between two places. Resolves place names or coordinates and returns distance, duration, and maps.
Instructions
Shortest-path walk, cycle, or drive between two places.
from_to is route() with LocationRef ends and a walk default; route is
the canonical routing tool and is growing the same from/to ends, so
prefer route(from=..., to=...) once it takes them.
Pass each of from/to as a free-text place name, a {"lat", "lon"} dict,
or a GERS id — mixed freely. Do not call geocode(), resolve_place(), or
geocode_batch() first. Plain names resolve in parallel exactly as
before; coordinates pass through untouched. Builds one street graph and
returns distance, duration, export maps/gpx/text, and a "from"/"to"
block carrying whatever the input resolved to (name/id when it was a
name or GERS id, lat/lon always).
A comma qualifies: "Alamo Square, SF" searches inside SF only.
If a name matches several equally-ranked places, returns
{"error": "ambiguous_place", "candidates": [...]} instead of picking
a city. If the two ends resolve a city apart, returns
{"error": "too_far"} with the resolved ends and the mode cap rather
than extracting a continent graph. Same per-mode straight-line caps
as a coordinate route (walk ~7.5 km, cycle ~23.5 km, drive ~95.5 km).
An unresolvable name or GERS id returns {"error": "not_found"}; a
malformed from/to (empty string, dict missing lat/lon, wrong type)
returns {"error": "bad_request"} — either way the offending side is
named in "field": "from" | "to". Omit mode to use the stored
preferences mode, else walk.
include_path, include_elevation, prefer, and avoid pass straight through
to route() — see that tool's docstring for what each returns/means
("elevation" climb profile, prefer="flat" grade-avoiding preference and
its honest step-free/accessibility caveats, avoid=["motorway"|"trunk"]
class avoidance and why no toll or ferry option exists). avoid needs
mode="drive": the walk default already excludes those classes.
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.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| to | Yes | ||
| from | Yes | ||
| mode | No | Travel mode. Default: stored preference, else walk. | |
| avoid | No | Road classes to keep the route off. No toll or ferry option exists: Overture carries no toll attribute, and the graph is road-only. Default: none (no class avoided). | |
| prefer | No | Grade preference. Default: none (plain-distance routing). | |
| confirm | No | ||
| include_path | No | ||
| include_elevation | No |
Output Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
No arguments | |||