Distance Matrix

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.

Try it first? Switch the Live Demo to the Distance Matrix tab and drag the markers around.

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`

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.

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

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"

# 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"

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")

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

Response

response-example.json

{
  "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`

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.

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 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 or your own VRP solver

Getting Started

API Reference

MCP

OpenAPI

Guides

Overview

Endpoint

Request Parameters

Service options

General options

Quickstart

Response

Response fields

Size limits

Errors

Recipes

​Overview

​Endpoint

​Request Parameters

​Service options

​General options

​Quickstart

​Response

​Response fields

​Size limits

​Errors

​Recipes

​Related

Overview

Endpoint

Request Parameters

Service options

General options

Quickstart

Response

Response fields

Size limits

Errors

Recipes

Related