​

HERE Matrix Routing

If you are calling the Routing API in a loop to build a table of travel times, stop reading and open your billing dashboard. This page will pay for itself. Matrix Routing computes travel times, distances, and consumptions between many origins and many destinations. One request. Not N×M.

​

What problem this guide solves

Depot-to-stop assignment. Nearest-driver dispatch. Service area analysis. Delivery zone economics. Every one of these needs a table of travel times, and every one of them is routinely built by looping a point-to-point routing API until the invoice arrives. A 200×3,000 matrix is 600,000 routing calls. Or it is one matrix request.

​

When to use Matrix Routing

• Assigning jobs to the nearest available vehicle
• Depot-to-stop distance tables feeding an optimizer
• Service-area or catchment analysis
• Comparing candidate warehouse locations by aggregate drive time
• Any question of the form “travel time between all of these and all of those”

​

When NOT to use it

• A single A→B route with a polyline. Use Routing. Matrix returns times and distances, not turn-by-turn geometry.
• Ordering stops into an itinerary. Matrix gives you the cost table. Tour Planning solves the ordering. Feeding a matrix into your own solver is legitimate; expecting matrix to do the solving is not.
• Real-time UI where the user waits. Large matrices are asynchronous by design. Submit, poll, retrieve.

​

The endpoint

Matrix Routing v8 lives at https://matrix.router.hereapi.com/v8, with /matrix for submission. It supports both apiKey (query parameter) and Bearer token authentication. The service operates in three modes, selected by the regionDefinition and profile parameters: The capabilities and limits of each mode differ meaningfully. HERE documents the trade-offs in the Matrix Routing v8 category.

​

Sync and async

Matrix calculation is available synchronously and asynchronously. Async is the mode that matters at production scale. The flow, per HERE’s specification:

1. POST the matrix request
2. Receive a matrixId and a statusUrl
3. Poll the statusUrl — use the URL HERE returns, not one you construct
4. On completion, retrieve the result

The response contains numOrigins, numDestinations, and flat arrays travelTimes and distances. This failure mode is the reason matrix bugs survive code review. Nothing crashes.

​

What are the size limits?

The practically important fact is directional and uncontested: matrix mode handles origin-destination sets at a scale where looping point-to-point routing is not merely more expensive but architecturally infeasible.

​

Production architecture

Async is not a synchronous call with a wait. Submit, get an ID, return control to your caller, poll on a worker. Wrapping this in a blocking facade with a 30-second timeout reproduces every problem async was designed to eliminate. Persist the matrixId. If your process dies mid-poll, you need to resume, not resubmit. Resubmitting bills again. Follow statusUrl exactly as returned. HERE explicitly warns against constructing it. It may redirect to the result on completion. Handle 429 on submission. Concurrent job limits exist. Back off; do not hammer. Truck parameters apply. Matrix accepts truck mode and vehicle constraints — the same grossWeight, axleCount, and dimensional parameters described in Truck Routing. A truck matrix built from car travel times is wrong in exactly the way a car route is wrong for a truck. Cache matrices keyed on the input set. Depot locations rarely move. If neither the origins, the destinations, nor the departure time changed, the matrix did not change.

​

Cost and usage considerations

Matrix operations are where the cost gap against Google is widest, and where the gap against your own looping implementation is widest of all. Run the arithmetic before you optimize anything else:

• Count your current routing calls that exist solely to populate a distance table
• That number, divided by the matrices it should have been, is your multiplier

Where teams overspend:

• Rebuilding an unchanged depot matrix nightly
• Computing a full matrix when a bounded region would have sufficed
• Requesting consumptions when only travelTimes is consumed downstream
• Submitting one matrix per vehicle when one matrix per depot would serve all of them

See HERE Pricing Explained.

​

Common mistakes

Looping the Routing API. The reason this page exists. Indexing the flat result array as if it were nested. Silently transposed. Nothing errors. Constructing the statusUrl instead of using the returned one. Blocking on an async job. Timeouts, retries, duplicate submissions, double billing. Losing the matrixId on process restart. Resubmission is a full recharge. Building a truck matrix in car mode. Wrong times, wrong assignments, wrong dispatch. Architecting against a size ceiling read from a comparison table. Read the spec. Requesting fields nothing downstream reads.

​

Best practices

• Treat async as async: submit, persist the ID, poll on a worker
• Follow statusUrl verbatim
• Write one indexing helper for the flat arrays and unit-test it against a known 2×2
• Cache on the hash of the input set
• Pass truck parameters when routing trucks
• Request only the fields you consume
• Confirm mode-specific size limits against the OpenAPI spec and your entitlement

​

API reference

• Matrix Routing API v8
• OpenAPI specification — authoritative on limits, modes, and parameters

​

Related guides

Also: EV Routing · HERE vs Google Maps · Authentication

---

Need production HERE API keys or implementation support? Placematic is an official HERE Technologies reseller and implementation partner helping companies choose the right HERE APIs, estimate usage, migrate from Google Maps and build production-ready geospatial solutions. Talk to us.