Distance Matrix

POST/routing/matrix

Calculate distances and durations between multiple origin and destination points. Returns a matrix where each cell contains the travel metrics from a source to a destination.

Request Body

Field	Type	Required	Description
`sources`	Coordinates[]	Yes	Origin points
`destinations`	Coordinates[]	Yes	Destination points
`departure`	ISO8601	No	Departure time for traffic calculation

Coordinates

Field	Type	Required	Description
`lat`	number	Yes	Latitude
`lng`	number	Yes	Longitude

{ "lat": 40.7128, "lng": -74.0060 }

Example Response

{
  "durations": [[720, 900, 1080]],
  "distances": [[5000, 6200, 7500]]
}

Response Fields

Field	Type	Description
`durations`	number[][]	Duration matrix in seconds
`distances`	number[][]	Distance matrix in meters

Matrix Structure

The response is a 2D array where:

durations[i][j] is the duration from sources[i] to destinations[j]
distances[i][j] is the distance from sources[i] to destinations[j]

Example with Multiple Sources

Request:

{
  "sources": [
    { "lat": 40.7128, "lng": -74.0060 },
    { "lat": 40.7580, "lng": -73.9855 }
  ],
  "destinations": [
    { "lat": 40.7484, "lng": -73.9857 },
    { "lat": 40.7614, "lng": -73.9776 }
  ]
}

Response:

{
  "durations": [
    [600, 720],
    [300, 420]
  ],
  "distances": [
    [4500, 5200],
    [2100, 2800]
  ]
}

Use Cases

Driver Assignment: Find the closest driver to a pickup location
Route Planning: Pre-compute distances for optimization algorithms
Service Area Analysis: Determine reachability within time thresholds
ETA Estimation: Calculate travel times for multiple destinations

Performance

The matrix calculation scales with sources * destinations. For large matrices, consider:

Batching requests for very large point sets
Using departure time for accurate traffic-based estimates
Caching results for static location pairs

On this page