---
title: Distance matrix | Plaza Docs
description: Compute travel time and distance between every combination of origins and destinations in a single request.
---

A distance matrix returns travel time and distance for every origin/destination pair. 3 origins x 4 destinations = 12 results in one request.

Distance matrices are a [premium endpoint](/guides/authentication#premium-endpoints/index.md) — each request counts as 4x.

## Basic request

Terminal window

```
curl -X POST https://plaza.fyi/api/v1/matrix \
  -H "x-api-key: pk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "origins": [
      { "type": "Point", "coordinates": [-73.9857, 40.7484] },
      { "type": "Point", "coordinates": [-73.9680, 40.7614] }
    ],
    "destinations": [
      { "type": "Point", "coordinates": [-74.0060, 40.7128] },
      { "type": "Point", "coordinates": [-73.9712, 40.7831] },
      { "type": "Point", "coordinates": [-73.9855, 40.7580] }
    ],
    "mode": "auto"
  }'
```

```
import Plaza from "@plazafyi/sdk";


const client = new Plaza();


const matrix = await client.v1.matrix({
  origins: [
    { type: "Point", coordinates: [-73.9857, 40.7484] },
    { type: "Point", coordinates: [-73.968, 40.7614] },
  ],
  destinations: [
    { type: "Point", coordinates: [-74.006, 40.7128] },
    { type: "Point", coordinates: [-73.9712, 40.7831] },
    { type: "Point", coordinates: [-73.9855, 40.758] },
  ],
  mode: "auto",
});
```

```
import plaza


client = plaza.Client()


matrix = client.v1.matrix(
    origins=[
        {"type": "Point", "coordinates": [-73.9857, 40.7484]},
        {"type": "Point", "coordinates": [-73.9680, 40.7614]},
    ],
    destinations=[
        {"type": "Point", "coordinates": [-74.0060, 40.7128]},
        {"type": "Point", "coordinates": [-73.9712, 40.7831]},
        {"type": "Point", "coordinates": [-73.9855, 40.7580]},
    ],
    mode="auto",
)
```

```
import "github.com/plazafyi/plaza-go"


client := plaza.NewClient()


matrix, _ := client.V1.Matrix(ctx, plaza.MatrixParams{
    Origins: []plaza.GeoJSONPoint{
        {Type: "Point", Coordinates: []float64{-73.9857, 40.7484}},
        {Type: "Point", Coordinates: []float64{-73.9680, 40.7614}},
    },
    Destinations: []plaza.GeoJSONPoint{
        {Type: "Point", Coordinates: []float64{-74.0060, 40.7128}},
        {Type: "Point", Coordinates: []float64{-73.9712, 40.7831}},
        {Type: "Point", Coordinates: []float64{-73.9855, 40.7580}},
    },
    Mode: "auto",
})
```

## Response

```
{
  "origins": [[40.7484, -73.9857], [40.7614, -73.9680]],
  "destinations": [[40.7128, -74.0060], [40.7831, -73.9712], [40.7580, -73.9855]],
  "matrix": [
    { "origin_index": 0, "destination_index": 0, "duration_s": 1020 },
    { "origin_index": 0, "destination_index": 1, "duration_s": 780 },
    { "origin_index": 0, "destination_index": 2, "duration_s": 420 },
    { "origin_index": 1, "destination_index": 0, "duration_s": 1380 },
    { "origin_index": 1, "destination_index": 1, "duration_s": 540 },
    { "origin_index": 1, "destination_index": 2, "duration_s": 360 }
  ],
  "pair_count": 6
}
```

Each entry maps back to your input arrays via `origin_index` and `destination_index`. To include distances, pass `"annotations": "duration,distance"` — entries will also have `distance_m` (meters).

Unreachable pairs return `null` for `duration_s`.

## Modes

| Mode      | Network                                |
| --------- | -------------------------------------- |
| `auto`    | Roads, one-ways, turn restrictions     |
| `foot`    | Sidewalks, footpaths, pedestrian zones |
| `bicycle` | Bike lanes, cycleways, shared roads    |

## Limits

Maximum 2500 pairs per request (origins x destinations), each list capped at 50 points. Split larger jobs into batches.

## Use cases

**Delivery assignment.** Build a 5x20 matrix to assign each order to the nearest driver by travel time.

**Nearest facility.** Find 10 candidate pharmacies, then build a 1x10 matrix to rank by actual drive time instead of straight-line distance.

**Fleet optimization.** Get time costs between every pair of stops. Feed the matrix into your own solver for finer control than `/optimize`.