Distance matrix
distance_matrixRead-onlyIdempotent
Calculate straight-line (great-circle) distances in meters between up to 10 origins and 10 destinations for spatial analysis.
Instructions
Straight-line (great-circle) distance in meters between every origin and destination.
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 10 each (100 pairs max). This is a plain haversine
calculation, not a routed distance or travel time, so it's cheap but it
is NOT what Google/Mapbox distance-matrix APIs return: no roads, no
turns, no travel time. For "how far can I get in N minutes" use
isochrone() instead; for actual routed times/distances between several
points use travel_time_matrix().
An id/name that failed to resolve returns an indexed error
(origins[i]: ... or destinations[i]: ...) with candidates on ambiguity
— checked after the 10-point cap, so an over-cap list always fails on
the cap first. Any origin/destination given by id/name adds "resolved":
{"origins": [{"index", "name", "id", "lat", "lon", "matched_by"}, ...],
"destinations": [...]} covering just those entries; each side is
present only if it had a string entry, and the whole key is absent when
every point was already coordinates.
Returns {"elements": [{"origin_idx": 0, "dest_idx": 0, "distance_m":
812}, ...]}, flat and origin-major (all destinations for origin 0,
then origin 1, ...), budgeted like every other tool. Empty origins or
destinations returns {"elements": []}. Returns a structured {"error":
"bad_request", ...} instead of raising if either list exceeds 10
points or a point is missing/non-numeric lat or lon.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| origins | Yes | ||
| destinations | Yes |
Output Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
No arguments | |||