Distance matrix

Compute in a single call the distances and durations between N origins and M destinations.

The Distance Matrix endpoint computes in a single request the distance and duration between each (origin × destination) pair. Ideal for:

finding the closest resource (driver, ambulance, expert…),
showing a “trip duration” table in a UI,
feeding a client-side optimization solver.

Endpoint

POST https://api.tmaps.tn/distance-matrix?api_key=YOUR_API_KEY

Parameters

JSON body

Param	Type	Requis	Défaut	Description
`origins`	array	oui	—	List of `{ lat, lng }` points (max 25).
`destinations`	array	oui	—	List of `{ lat, lng }` points (max 25).
`profile`	string	—	`driving`	Transport profile: `driving`, `walking`, `cycling`, `truck`.
`metrics`	array	—	`["duration","distance"]`	Metrics to return. At least one of: `duration`, `distance`.

Size limit

Maximum 25 origins × 25 destinations per request, i.e. 625 pairs. For larger matrices, batch and merge the results client-side.

Example — find the nearest ambulance

curl -X POST "https://api.tmaps.tn/distance-matrix?api_key=YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
  "origins": [
    { "lat": 36.8280, "lng": 10.2100 },
    { "lat": 36.8450, "lng": 10.1850 },
    { "lat": 36.8094, "lng": 10.1400 }
  ],
  "destinations": [
    { "lat": 36.8000, "lng": 10.1815 }
  ],
  "profile": "driving"
}'

Response

{
"durations": [
  [320],
  [180],
  [420]
],
"distances": [
  [3120],
  [1840],
  [4250]
],
"origins": [
  { "lat": 36.8280, "lng": 10.2100 },
  { "lat": 36.8450, "lng": 10.1850 },
  { "lat": 36.8094, "lng": 10.1400 }
],
"destinations": [
  { "lat": 36.8000, "lng": 10.1815 }
]
}

Reading the matrix

durations[i][j] = duration in seconds from origins[i] to destinations[j].
distances[i][j] = distance in meters for the same pair.
origins and destinations are returned in the request order, to ease client-side joins.

Symmetry

For a square matrix (same set as origins and destinations), durations[i][i] = 0 and the matrix can be asymmetric in urban areas because of one-way streets.

Use cases

Assignment: closest ambulance / driver / expert for a new case.
Site selection: compare travel times of N candidates to M targets.
Geomarketing: “store × customers” duration table for a coverage solver.

Errors

Status	Cause
`400`	Missing `origins`/`destinations`, or more than 25 points in either
`401`	Missing or revoked `api_key`
`403`	Domain not authorized
`404`	At least one coordinate outside coverage

See Error codes for the full list.