Travel time matrix
travel_time_matrixRead-onlyIdempotent
Calculate real travel times and distances between multiple origins and destinations using road network routing for walk, cycle, or drive modes. Avoid haversine approximations with actual shortest-path results.
Instructions
Routed travel time + distance between every origin and destination, by mode.
origins and destinations are each a list of LocationRefs — a {"lat":
..., "lon": ...} dict, a GERS id, or a free-text place name, mixed
freely — capped at 5 each (25 pairs max). Unlike distance_matrix's plain
haversine, this is a real shortest-path search over Overture's open
street graph — roads, one-ways, and each mode's own speed model, the
same cost model route() uses for a single pair, one mode per call;
omit mode to use the stored preferences mode, else walk.
An id/name that failed to resolve returns an indexed error
(origins[i]: ... or destinations[i]: ...) with candidates on ambiguity
— checked after the 5-point cap. Any origin/destination given by
id/name adds "resolved": {"origins": [{"index", "name", "id", "lat",
"lon", "matched_by"}, ...], "destinations": [...]} covering just those
entries; each side present only if it had a string entry, absent when
every point was already coordinates.
Reuses a single cached street graph across every origin and
destination when every origin-destination pair fits the mode's
straight-line cap and the whole point set fits one extraction circle,
running one Dijkstra per origin against every destination at once
rather than a search per pair — for a same-city matrix this costs
about what a single isochrone does, not one route() call per pair.
When the points are too spread out for one shared graph, falls back to
a route() call per pair (up to 25).
Returns {"mode", "elements": [{"origin_idx", "dest_idx", "duration_min",
"distance_m"}, ...], "durations_note"}, flat and origin-major like
distance_matrix. durations_note says these are speed-model estimates
over the open street graph, not live traffic. An unroutable pair (off
the street network, or on a disconnected fragment of it) gets
{"duration_min": null, "distance_m": null, "note": "unroutable"}
instead of failing the whole call; if every pair in the matrix is
unroutable the response also carries a top-level "note" saying so.
If the street graph hit its size cap the response carries "truncated":
true plus a note — capped extractions may present reachable pairs as
unroutable. Empty origins or destinations returns {"elements": []}.
Returns a structured {"error": "bad_request", ...} instead of raising
if either list exceeds 5 points, a point is missing/non-numeric lat or
lon, or mode isn't walk/cycle/drive. If no street graph exists
anywhere near every point in the matrix, returns {"error":
"no_graph_nearby"} — the same top-level failure route() and
optimize_route() give when nothing in the area is on the mapped
network, rather than a matrix of nulls.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| mode | No | Travel mode. Default: stored preference, else walk. | |
| origins | Yes | ||
| destinations | Yes |
Output Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
No arguments | |||