> ## Documentation Index
> Fetch the complete documentation index at: https://docs.justrouting.tech/llms.txt
> Use this file to discover all available pages before exploring further.

# Distance Matrix

> Compute travel times and distances between many points in a single request.

## Overview

Distance Matrix API returns an N×N matrix of driving times (seconds) and distances (meters) in a single request, powered by the `table` service. Ideal for nearest-store lookup, dispatch, and batch route planning.

<Tip>
  **Try it first?** Switch the [Live Demo](https://justrouting.tech) to the Distance Matrix tab and drag the markers around.
</Tip>

## Endpoint

```
GET https://api.justrouting.tech/table/v1/{profile}/{coordinates}
```

| URL parameter | Description |
| - | - |
| `profile` | `driving` or `motorcycle` |
| `coordinates` | `{lng},{lat};{lng},{lat}[;...]` |

## Request Parameters

### Service options

| Parameter | Type | Default | Description |
| - | - | - | - |
| `sources` | string | `all` | Source indices, e.g. `sources=0` or `sources=0;1` |
| `destinations` | string | `all` | Destination indices; combine with `sources` for cheaper asymmetric sub-matrices |
| `annotations` | string | `duration` | `duration` / `distance` / `duration,distance` |
| `fallback_speed` | float | — | When no route exists, estimate the duration from the as-the-crow-flies distance at this speed |
| `fallback_coordinate` | string | `input` | For fallback estimates, measure from `input` (user-supplied) or `snapped` coordinates |
| `scale_factor` | float | — | Scale all duration values, e.g. `1.2` = everything +20%; use with `annotations=duration` |

<Info>
  Unlike the array-encoded general options, `sources` and `destinations` may contain fewer entries than the number of input coordinates. With `skip_waypoints=true`, both arrays are skipped in the response.
</Info>

### General options

These options apply to all routing services. Options that take one value per coordinate use the array-like encoding `{option}={element};{element}[;...]` — the number of elements must match the number of coordinates (except `generate_hints` and `exclude`). Pass an empty element to use the default for that coordinate, e.g. `bearings=;90,20;`.

| Parameter | Type | Default | Description |
| - | - | - | - |
| `bearings` | string | — | Limit snapping to segments with the given bearing; each element is `{value},{range}` with value 0–360° clockwise from true north and range 0–180° |
| `radiuses` | string | — | Limit snapping to the given radius in meters per coordinate, `unlimited` for no limit |
| `generate_hints` | bool | `true` | Add a `hint` to each response source/destination waypoint for reuse in later requests via `hints` |
| `hints` | string | — | Base64 `hint` from a previous response; speeds up snapping significantly |
| `approaches` | string | — | Restrict the road direction at a waypoint; per element `curb` / `opposite` / `unrestricted` (default) |
| `exclude` | string | — | Additive list of road classes to avoid, e.g. `exclude=motorway` |
| `snapping` | string | `default` | `any` snaps to any edge in the graph; `default` avoids edges that cannot be used as start/end points |
| `skip_waypoints` | bool | `false` | Remove `sources` and `destinations` from the response (they are still calculated, just not serialized) |

## Quickstart

<CodeGroup>
  ```bash 3×3 duration matrix theme={null}
  curl "https://api.justrouting.tech/table/v1/driving/103.708362,1.357371;103.8514,1.2897;103.984748,1.352212" \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```

  ```bash Only the depot row theme={null}
  # sources=0: returns only row 0 — two-thirds cheaper
  curl "https://api.justrouting.tech/table/v1/driving/103.708362,1.357371;103.8514,1.2897;103.984748,1.352212?sources=0&annotations=duration,distance" \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```

  ```python Python theme={null}
  import justrouting

  client = justrouting.Client("YOUR_API_KEY")

  m = client.matrix.get(justrouting.MatrixRequest(
      coordinates=[[103.708362, 1.357371], [103.8514, 1.2897], [103.984748, 1.352212]],
      sources=[0],                    # only the depot row
      destinations=[1, 2],
      annotations=["duration", "distance"],
  ))

  print(f"depot → B: {m.duration(0, 1) / 60:.0f} min")   # may be None (unreachable)
  print(f"depot → C: {m.distance(0, 1) / 1000:.1f} km")
  ```

  ```ts JavaScript theme={null}
  import { Client } from '@justrouting/client';

  const client = new Client("YOUR_API_KEY");

  const m = await client.matrix.get({
    coordinates: [[103.708362, 1.357371], [103.8514, 1.2897], [103.984748, 1.352212]],
    sources: [0],
    destinations: [1, 2],
  });

  const minutes = m.duration(0, 1); // number | null
  ```
</CodeGroup>

## Response

```json response-example.json theme={null}
{
  "code": "Ok",
  "durations": [
    [0, 192.6, 382.8],
    [199, 0, 283.9],
    [344.7, 222.3, 0]
  ],
  "distances": [
    [0, 1886.89, 3791.3],
    [1824, 0, 2838.09],
    [3275.36, 2361.73, 0]
  ],
  "sources": [
    { "name": "", "location": [103.708362, 1.357371] }
  ],
  "destinations": [
    { "name": "", "location": [103.8514, 1.2897] },
    { "name": "", "location": [103.984748, 1.352212] }
  ]
}
```

### Response fields

| Field | Type | Unit | Description |
| - | - | - | - |
| `durations` | array\[]\[] | **seconds** | Row-major matrix; `durations[i][j]` is source i → destination j |
| `distances` | array\[]\[] | **meters** | Same layout (returned with `annotations=distance`) |
| `sources` / `destinations` | array | — | Snapped source/destination coordinates |
| `fallback_speed_cells` | array | — | `[i, j]` cells estimated via `fallback_speed` |

<Warning>
  A `null` cell means **no route exists** between that pair — it is deliberately distinct from a real 0. The official SDKs preserve `null` instead of coercing it to 0.
</Warning>

## Size limits

| Plan | Max matrix |
| - | - |
| Free | 100 × 100 |
| Hobby | 500 × 500 |

Exceeding the limit returns `400 TooBig`. For large matrices: trim to the sub-matrix you need with `sources`/`destinations`, compute in batches, and cache the results — matrices are stable and rarely need real-time recomputation.

## Errors

| HTTP | code | Meaning |
| - | - | - |
| 400 | `NoTable` | No routable cell in the matrix — use `fallback_speed` as a fallback |
| 400 | `NotImplemented` | The request is not supported |

See [Errors](/errors) for the full list.

## Recipes

* **Nearest store**: `sources=0` (the user) against `destinations=all`, pick the column with the smallest duration
* **Dispatch planning**: feed the matrix into [Fleet Optimization](/api-reference/fleet-optimization) or your own VRP solver

## Related

* [Directions API](/api-reference/directions)
* [Fleet Optimization](/api-reference/fleet-optimization)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.