# Matrix

Get durations and distances from every source to every destination.

`POST /v2/matrix`. Auth: API key, or a test map trial run.

## Request body

Send JSON with `Content-Type: application/json`.

| Field | Required | Description |
|---|---|---|
| `sources` | Yes | 1 to 25 `[lng, lat]` pairs |
| `destinations` | Yes | 1 to 25 `[lng, lat]` pairs |
| `profile` | No | `car` (default) or `car_night` |

`sources.length × destinations.length` must be at most 25, or the request is `400 too_many_cells` before any work is done.

## Example

```bash
curl -s -X POST -H 'Content-Type: application/json' -H "X-API-Key: $QUADRUPER_KEY" \
  -d '{"sources":[[122.5621,10.7202]],"destinations":[[122.5444,10.6969],[122.53,10.70]]}' \
  https://quadruper.com/v2/matrix
```

This is an example response:

```json schema=matrix-response
{
  "sources": [{ "location": [122.5621, 10.7202], "snapped": true }],
  "destinations": [{ "location": [122.5444, 10.6969], "snapped": true }, { "location": [122.53, 10.7], "snapped": false }],
  "durations_s": [[690.0, null]],
  "distances_m": [[4210.0, null]],
  "conditions": { "assessed": false, "reason": "not_configured" },
  "attribution": [{ "source": "osm", "text": "© OpenStreetMap contributors", "license": "ODbL-1.0" }]
}
```

## Response fields

| Field | Description |
|---|---|
| `durations_s`, `distances_m` | Rows follow `sources`, columns follow `destinations`. |
| A `null` cell | No route, or a point couldn't be snapped. It isn't an error. |
| `sources[]`, `destinations[]` | `location` is where the point snapped. `snapped: false` echoes the input location. |

## Limits and failures

- **Rate limit:** 1 request per second per key, with a burst of 3. Over it, you get `429`.
- **Time limit:** a matrix that runs out of time fails with `504 engine_timeout`. You never get a partly filled matrix.
- **Availability:** a deployment can switch the matrix off. It then answers `501 capability_unavailable`, and `GET /v2/info` doesn't list `matrix`.
- **`out_of_coverage`:** `details.point_index` counts the sources first and then the destinations. With 3 sources, `point_index: 4` is the second destination.

In rare cases a cell's error can fail the whole matrix. If that error has a `point_index`, it is `0` for the cell's source or `1` for its destination, not a matrix index.

See [Compare travel times with a matrix](../guides/matrix.md) for how to use the result.