/matrix Travel times and distances between every source and every target in one request.
Also known as a sources-to-targets or OD (origin-destination) matrix. Send up to N sources and M targets, get back an NxM grid of real road-network durations and distances, not straight-line estimates. Essential for any system that needs to compare travel costs across multiple origin-destination pairs at once.
Part of the Routing API family alongside Directions, Isochrone, and Optimised Route.
# 2 depots → 3 delivery stops: 2×3 travel-time matrix
curl -X POST "https://api.farun.one/matrix" \
-H "X-RapidAPI-Key: YOUR_KEY" \
-H "X-RapidAPI-Host: farun-maps.p.rapidapi.com" \
-H "Content-Type: application/json" \
-d '{
"sources":[
{"lat": -33.9249, "lon": 18.4241},
{"lat": -33.9652, "lon": 18.4783}
],
"targets":[
{"lat": -33.8688, "lon": 18.5209},
{"lat": -34.0034, "lon": 18.4621},
{"lat": -33.9318, "lon": 18.8601}
],
"costing": "auto",
"units": "kilometers"
}'Output shape
NxM grid of cells
Road network
Real routes, not haversine
Costing modes
auto, truck, bicycle, pedestrian
How the matrix is computed
The Matrix API runs a many-to-many shortest-path expansion
across the road network using Valhalla. It computes real
driving (or cycling, walking, truck) durations and distances
for every source-to-target pair simultaneously, returning a
structured grid you index by sources_to_targets[i][j].
Step 1
Supply any number of source coordinates (origins) and target coordinates (destinations) as lat/lon pairs. Sources and targets can overlap - a location can appear in both arrays if needed.
Min: 1 source, 1 target. No hard upper limit documented. Step 2
Valhalla performs a many-to-many cost expansion across the road graph using your chosen costing mode. Every source fans out until all targets are reached, producing real travel durations and road distances along the actual network.
Powered by Valhalla sources_to_targets. Step 3
The response contains a sources_to_targets array - an outer array indexed by source, each containing an inner array indexed by target. Access any cell as sources_to_targets[i][j] to get time in seconds and distance in your chosen unit.
Index: [source_index][target_index] Who uses it
The Matrix API replaces N individual route calls with a single batched request. Any system that needs to find the nearest depot, assign a driver to a job, or pre-compute a cost table for an optimisation solver should use the matrix rather than looping over individual route requests.
Last-Mile Delivery
Given a list of pending deliveries and a list of depot locations, compute the full travel-time matrix and assign each delivery to the depot with the lowest travel cost. One matrix call replaces NxM individual route requests.
Field Service & Scheduling
Before running a route optimisation or job-scheduling algorithm, pre-compute the matrix of travel times from every available driver to every open job. Feed the resulting cost table directly into your assignment solver or VRP engine.
Retail & Site Planning
Measure real drive times from a candidate site to a set of population centres or competitor locations. Use the matrix to score prospective sites by accessibility before committing to a lease or build.
Emergency & Healthcare
Compute travel times from all available ambulances or field units to an incident location, then dispatch the nearest one. For healthcare networks, find the closest facility with capacity from any patient origin in a single request.
Response shape
The sources_to_targets array is indexed [source_index][target_index]. Each cell contains the travel time in seconds and distance in your requested unit. A null cell means no route was found between that pair on the road
network.
sources_to_targets Outer array (length = N sources), each element is an array of M target cells [i][j].time Travel time in seconds from source i to target j along the road network [i][j].distance Road distance in the requested unit (kilometers or miles) [i][j].to_index Index of the target in the original targets array - useful for referencing back [i][j].date_time Estimated arrival time if departure time was specified in costing_options sources[].lat/lon Snapped coordinates of each source on the road network targets[].lat/lon Snapped coordinates of each target on the road network units Echoed unit string from the request (kilometers or miles) {
"sources_to_targets": [
/* source 0 → all targets */
[
{ "to_index": 0, "time": 842, "distance": 18.3 },
{ "to_index": 1, "time": 1205, "distance": 24.7 }
],
/* source 1 → all targets */
[
{ "to_index": 0, "time": 614, "distance": 11.2 },
{ "to_index": 1, "time": 389, "distance": 7.6 }
]
],
"sources": [
{ "lat": -33.9249, "lon": 18.4241 },
{ "lat": -33.9652, "lon": 18.4783 }
],
"targets": [
{ "lat": -33.8688, "lon": 18.5209 },
{ "lat": -34.0034, "lon": 18.4621 }
],
"units": "kilometers"
}
Read any cell as sources_to_targets[sourceIdx][targetIdx]. A null cell means no route
found on the network.
Endpoint reference
https://api.farun.one/matrix Request body (JSON)
sources
req
targets
req
costing costing_options units Costing modes
auto Passenger car. Default. Uses live-like road speeds and turn restrictions. truck Heavy goods vehicle. Respects weight limits, height clearances, and hazmat restrictions via costing_options. bicycle Bicycle routing. Prefers cycle paths and low-traffic roads. pedestrian Walking. Uses footpaths and crossings; avoids motorways. motorcycle Motorcycle. Similar to auto but prefers higher-speed roads. Response codes
200 application/json N×M matrix grid in sources_to_targets. 400 Bad request Missing sources or targets, or malformed coordinates. 401 Unauthorized Missing or invalid RapidAPI key. 422 Unprocessable A location could not be snapped to the road network. 429 Rate limited Daily pool exhausted. Upgrade on RapidAPI. 503 Unavailable Routing backend unavailable. Output
sources_to_targets[i][j]
Time field
Seconds (integer)
Distance
km or miles (float)
No-route cell
null in the grid
Costing
auto, truck, bicycle, pedestrian, motorcycle
Units
kilometers (default) or miles
Integration example
// Assign each delivery to the nearest depot by travel time
const depots = [ /*[{lat,lon}, ...] */ ];
const deliveries = [ /* [{lat,lon}, ...] */ ];
const res = await fetch("/api/matrix-proxy", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({
sources: depots, // origins = depots
targets: deliveries, // targets = jobs
costing: "auto",
units: "kilometers",
}),
});
const { sources_to_targets } = await res.json();
// For each delivery, find the depot with minimum travel time
const assignments = deliveries.map((_, jobIdx) => {
let bestDepot = 0, bestTime = Infinity;
sources_to_targets.forEach((row, depotIdx) => {
const t = row[jobIdx]?.time ?? Infinity;
if (t < bestTime) { bestTime = t; bestDepot = depotIdx; }
});
return { job: jobIdx, depot: bestDepot, time_s: bestTime };
});Always proxy server-side. Never POST to the API directly from client-side JavaScript, your RapidAPI key would be exposed. Route all requests through your own backend endpoint.
Navigation API family
Turn-by-turn routes between waypoints with full geometry and instructions.
Solve the Travelling Salesman Problem to find the most efficient stop order.
Compute many-to-many travel times and distances in a single batched request.
Generate reachability polygons based on travel time or physical distance.
Often used together
Feed the matrix output into the optimized route endpoint to solve the travelling salesman or VRP problem across your stops.
Geocode addresses to coordinates, then pass the resolved lat/lon directly as matrix sources or targets.
After identifying nearest locations via the matrix, generate reachability polygons for service area visualisation.
Render the computed routing paths or polygons onto a vector tile map layer.
Start building
Free tier on RapidAPI. 1,000 requests per day across all non-tile APIs combined. No credit card required.