Distance matrix

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 — each request counts as 4x.

Basic request

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.