A distance matrix is a grid of travel times and distances between many origins and many destinations. It is the data structure behind every "nearest store" ranking, every delivery dispatch decision, and every route optimisation solver. Whenever an application has to pick the best of many candidates by drive time, a distance matrix is doing the work underneath.
This guide explains what a distance matrix actually is, how travel time differs from straight-line distance, where matrices show up in production systems, and which pitfalls bite teams once the input set grows beyond a handful of points.
What a Distance Matrix Really Is
In its simplest form, a distance matrix is a two-dimensional table. The rows are origins, the columns are destinations, and each cell holds two numbers: a distance and a duration. With N origins and M destinations, the matrix has N times M cells. A request with 25 drivers and 25 jobs produces 625 cells in a single call.
The values in those cells come from a routing engine that walks a real road network graph. It picks the fastest path from each origin to each destination, sums the segment costs, and returns the total. That is fundamentally different from a haversine calculation, which draws a straight line between two coordinates and ignores the fact that buildings, rivers, and one-way streets exist.
A coordinate pair tells you where two points are. A distance matrix tells you what it actually costs to get between them.
Distance vs Duration
Three different numbers often get called "distance", and confusing them is the most common bug in routing code.
Haversine distance is the great-circle distance between two latitude and longitude pairs. It is fast to compute, requires no network call, and is wrong for any task that involves driving. A 2 km haversine distance can be a 7 km drive once you account for the river you cannot cross.
Road-network distance is the length of the actual driveable path. It accounts for one-way streets, turn restrictions, and the topology of the road graph. This is what a distance matrix API returns in the distance field.
Duration with traffic is the time the trip will take given current or predicted traffic conditions. A 12 km motorway segment is six minutes at 02:00 and twenty-five minutes at 17:30. Production systems that care about ETAs ask for traffic-aware durations and pass a departure time so the routing engine can model congestion correctly.
For ranking and dispatch, duration almost always wins over distance. A driver does not care that the closer job is 800 metres further away if it shaves four minutes off the drive.
Where Distance Matrices Show Up
Distance matrices are quietly running underneath most logistics and location-aware features.
- Delivery driver assignment: each pending order is matched against each available driver. The dispatcher picks the cell with the lowest duration that respects vehicle capacity and shift constraints
- Fleet dispatching and rebalancing: ride-hailing and last-mile platforms compute matrices between vehicles and demand zones every few seconds to keep cars near the riders
- Store and venue locator ranking: instead of returning the five closest stores by haversine, the locator computes a small matrix from the user's location to the candidates and ranks by drive time
- ETA calculations at scale: marketplaces with many simultaneous orders batch ETAs into matrix calls rather than firing thousands of single-route requests
- VRP solvers: vehicle routing problem solvers (OR-Tools, jsprit, commercial optimisers) require a full cost matrix as input. The quality of the routing solution is bounded by the quality of the matrix you feed it
- Site selection and territory planning: analysts compute matrices between candidate locations and customer clusters to pick the warehouse that minimises total drive time
In all of these, the matrix is the bulk-computation primitive. It is what lets a system reason about "the best of many" without paying the cost of N times M individual routing calls.
Pitfalls in Production
Distance matrices are easy on day one and get harder fast.
Asymmetry is the default. Real road networks have one-way streets, divided carriageways, and asymmetric turn costs. The cell at (A, B) is rarely equal to the cell at (B, A). Treating the matrix as symmetric to save memory is one of the classic causes of wrong-way routing in dispatch systems.
The N times M cost. A 100 by 100 matrix is 10,000 cells. A 500 by 500 matrix is 250,000 cells. Costs and latency grow quadratically. Most production systems batch matrices into chunks (50 by 50 or 100 by 100), parallelise the requests, and cache results that do not change often, like the matrix between a fixed set of warehouses and a fixed set of stores.
Time-of-day variance. A matrix computed at 03:00 is not valid at 17:00. If your dispatch logic depends on traffic, either request a traffic-aware matrix at decision time or pre-compute a small set of time-bucketed matrices (morning peak, off-peak, evening peak) and pick the right one.
Batching and rate limits. Distance matrix APIs charge per element, not per request, and most providers cap the size of a single call. Plan for chunking and back-pressure from day one rather than discovering it at scale.
Coordinate quality in, garbage out. A matrix is only as good as the coordinates feeding it. A geocode that landed on the wrong side of a divided highway will produce a wildly wrong duration. Validate input coordinates before they enter the matrix request.
Distance Matrices in MapAtlas
The MapAtlas Distance Matrix API computes full N by M matrices of travel time and distance over a real European and global road network. It supports car, truck, bicycle, and pedestrian profiles, accepts traffic-aware requests with a departure time, and is built for the batch sizes that real dispatch and optimisation workloads need.
For workloads that go beyond ranking, the Distance Matrix API pairs naturally with the Optimize Route API, which takes a matrix and a set of stops and returns an ordered route that minimises total drive time, and with the Isochrone API for "everything reachable within X minutes" filters that pre-shrink the candidate set before the matrix call.
A distance matrix is not glamorous. It is just a grid of numbers. But it is the grid of numbers that turns "find the best of many" from an N times M routing nightmare into a single bulk request, and getting that one piece of data right is what separates a real logistics product from a demo with five pins on a map.
Frequently Asked Questions
What is a distance matrix?
A distance matrix is an N by M grid of travel times and distances between a set of origins and a set of destinations. Each cell answers a single question: how long does it take to get from origin i to destination j, and how far is it. Modern distance matrix APIs compute the values over a real road network rather than as straight-line distances, so the results account for one-way streets, turn restrictions, and routable geometry.
What is the difference between distance and duration?
Distance is how far you travel along the road network in metres or kilometres. Duration is how long it takes, in seconds, accounting for speed limits, traffic, and road class. They are not interchangeable. Two routes can have the same distance and very different durations, and most production use cases (ETA, dispatch, ranking) care about duration. A good distance matrix API returns both for every cell.
When should I use a distance matrix instead of single routes?
Use a distance matrix whenever you need to compare many candidates: ranking the closest five stores out of fifty, assigning a delivery to the nearest available driver out of twenty, or feeding a vehicle routing problem solver. Calling a single routing endpoint N by M times is slow and expensive. A matrix endpoint returns the same data in one request, optimised for bulk computation.
Are distance matrices symmetric?
Almost never in real road networks. The drive from A to B is rarely the same as B to A because of one-way streets, divided highways, turn restrictions, and asymmetric traffic. A production distance matrix API returns a full N by M grid, not a triangular half. If you collapse the matrix to save memory, you will route drivers down the wrong side of the road.
