A distance matrix API returns the travel time and distance between every combination of a set of starting points and a set of destinations, in a single request. Ask it about three warehouses and five delivery addresses and you get back all 15 pairs at once. The Stadia Maps Time/Distance Matrix API "lets you compare travel times between a set of possible start and end points," using the same road network and travel modes as the rest of the Stadia Maps Routing API.

The question a matrix answers is "which of these is closest?" It is not the same question a routing API answers, which is "how do I get from here to there?"

Key Takeaways

  • A distance matrix returns times and distances for every source-and-target pair. Elements equal sources multiplied by targets, so three sources and five targets is 15 elements.
  • Use a matrix to rank or assign. Use standard routing to actually navigate, because a matrix returns no route geometry or turn-by-turn instructions.
  • Stadia Maps bills the matrix at 10 credits per element, against 20 credits per request for standard routing. Ranking 10 destinations costs 100 credits as a matrix and 200 as 10 separate route calls.
  • Matrix size caps at 625 elements on Standard and 10,000 on Professional, with a distance limit of 400km for auto, bus, truck, and taxi, and 200km for other modes.
  • Traffic-influenced profiles work here through the _traffic and _traffic_premium suffixes, and require a Standard plan or higher.

Matrix, Routing, or Isochrone: Which Do You Need?

These three endpoints answer three different questions, and picking the wrong one is the most common and most expensive mistake in this part of an API.

  • "How do I get from A to B?" Use standard routing. It returns the path, the geometry, and turn-by-turn instructions.
  • "Which of these N places is closest to me?" Use the Time/Distance Matrix. It returns a ranked set of times and distances and no path at all.
  • "What area can I reach in 20 minutes?" Use isochrones. It returns a polygon, not a list of places. What Is an Isochrone? covers that side in depth, including when a polygon beats a ranking.

The matrix is the one teams reach for last and should often reach for first. Dispatch, store locators, and delivery assignment all look like routing problems, and all of them are really ranking problems. You need to know which driver is nearest, not how that driver turns left.

How a Matrix Request Works

You send two arrays and a travel mode. The API returns the grid.

  • sources: the starting locations, each with a latitude and longitude.
  • targets: the destinations, in the same shape.
  • costing: the travel mode. auto, pedestrian, bicycle, truck, taxi, and bus are among the documented options.
  • date_time: optional, for traffic-influenced profiles, in YYYY-MM-DDTHH:MM format.
  • costing_options: optional vehicle-specific preferences.

The endpoint is https://api.stadiamaps.com/matrix/v1. Full parameter detail is in the Time/Distance Matrix docs.

One documented constraint that bites in production: you cannot combine a root-level date_time with per-waypoint date_time. Pick one.

A one-to-many matrix is the most common shape. One source, many targets, which gives you a ranked list of destinations from a single origin. Many-to-many is what fleet and dispatch systems use, and it is where the element count grows fastest.

What a Matrix Costs, and Why the Shape Matters

Stadia Maps bills the Time/Distance Matrix at 10 credits per element, where an element is one source-and-target pair. Standard routing bills at 20 credits per request.

That pricing shape rewards asking the right question. Ranking 10 destinations from one origin is 10 elements, or 100 credits. Doing the same work as 10 separate routing calls is 200 credits, and you wait on 10 round trips instead of one.

It also punishes the wrong shape. Elements multiply, so a 50-by-50 matrix is 2,500 elements, not 100. If you only need the times from one depot, send one source and 50 targets rather than a square matrix you will throw away most of.

The tradeoff is what you give up. A matrix returns times and distances, and no geometry and no instructions. If you need to draw the route on a map or give a driver directions, you still need a routing call for the pair you selected. The common pattern is matrix first to choose, routing second to navigate.

Matrix Size Limits

Limits are documented per plan, and they apply to elements rather than to locations.

Travel modeStandardProfessionalDistance limit
Auto, bus, truck, taxi625 elements10,000 elements400km
Other modes625 elements10,000 elements200km

625 elements is a 25-by-25 matrix, or one source against 625 targets. 10,000 elements is 100 by 100.

Element caps are documented for the Standard and Professional plans. Check the service limits documentation and the pricing page for what applies to your plan. For contrast, standard routing and optimized routing each cap at 50 locations per route.

Traffic-Influenced Matrices

The same traffic-influenced profiles available elsewhere in the routing API apply here, through the _traffic and _traffic_premium suffixes on supported costing models. Stadia Maps traffic profiles carry current and historical conditions for over 80 countries.

This matters more for a matrix than for a single route. A dispatch decision made on free-flow speeds sends the wrong driver at 17:30, and the error compounds across every assignment in the batch. Traffic-influenced routing requires a Standard plan or higher.

Common Distance Matrix Use Cases

  • Dispatch and driver assignment. Score every available driver against every open job, then assign on the ranking rather than on straight-line distance.
  • Store and branch locators. Return the three nearest locations by drive time instead of by radius, which is the difference between a useful result and one with a river in the way.
  • Delivery and service-area planning. Feed the matrix into a solver. Stadia Maps documents integration with OptaPlanner and VROOM for rich vehicle routing problems.
  • Field sales territory design. Cluster accounts by travel time from a rep's base rather than by postal code.
  • Marketplace supply matching. Rank nearby providers by how long they would actually take to arrive.

For the single-vehicle case, where you need the best order to visit a set of stops rather than a ranking, Optimized Routing solves the traveling salesman shape directly.

Frequently Asked Questions

What is a distance matrix API?

A distance matrix API returns the travel time and distance between every combination of a set of starting points and a set of destinations in one request. The Stadia Maps Time/Distance Matrix API lets you compare travel times between a set of possible start and end points, using the same road network and travel modes as the rest of the routing API.

What is the difference between a distance matrix and a routing API?

A routing API answers how to get from one place to another and returns the path, geometry, and turn-by-turn instructions. A distance matrix answers which of several places is closest and returns only times and distances, with no route geometry. The common pattern is to call the matrix first to choose a destination, then call routing for the pair you selected.

How is a distance matrix request billed on Stadia Maps?

The Time/Distance Matrix is billed at 10 credits per element, where an element is one source-and-target pair. Standard routing is billed at 20 credits per request. Ranking 10 destinations from a single origin is 10 elements, or 100 credits, against 200 credits for the same work as 10 individual routing calls.

How large can a distance matrix be?

Matrix size is capped at 625 elements on the Standard plan and 10,000 elements on the Professional plan, where elements equal sources multiplied by targets. There is also a distance limit of 400km for auto, bus, truck, and taxi, and 200km for other travel modes. The service limits documentation lists the caps that apply to each plan.

Does a distance matrix account for traffic?

It can. Traffic-influenced profiles are available through the _traffic and _traffic_premium suffixes on supported costing models, and Stadia Maps traffic profiles carry current and historical conditions for over 80 countries. Traffic-influenced routing requires a Standard plan or higher.

What travel modes does the Stadia Maps matrix support?

The documented costing options include auto, pedestrian, bicycle, truck, taxi, and bus. The broader routing API also offers specialized profiles for trucks, motor scooters, and other vehicle types.

Where to Go Next

Routing & Navigation