Distance matrices

​

What goes into the matrix

• each job’s location
• each shipment’s pickup.location and delivery.location
• each shift’s start and end, whether given inline or as a depots[].id
• each depot a shift lists in reloads
• the location of a driver break that is pinned to a place

​

Fields that control travel data

{
  "problem": {
    "travel": {
      "engine": "tomtom",
      "departure_time": "2026-07-01T08:00:00+02:00"
    },
    "depots": [{ "id": "gent", "location": [3.7174, 51.0543] }],
    "vehicles": [
      {
        "id": "van-1",
        "profile": "car",
        "shifts": [
          {
            "id": "wed",
            "from": "2026-07-01T08:00:00+02:00",
            "to": "2026-07-01T17:00:00+02:00",
            "start": { "depot": "gent" },
            "end": { "depot": "gent" }
          }
        ]
      }
    ],
    "jobs": [
      { "id": "job-1", "location": [3.7250, 51.0500], "service_duration_s": 300 },
      { "id": "job-2", "location": [3.7100, 51.0600], "service_duration_s": 600 }
    ]
  }
}

​

Choosing an engine

​

Adjusting travel and service time per vehicle

​

What the matrix drives

• Feasibility. Time windows, shift hours, and the route limits vehicles[].limits.max_distance_m and vehicles[].limits.max_route_duration_s are all checked against them.
• Cost. objective.costs.per_travel_km is charged on route distance, and objective.costs.per_route_hour on each route’s start-to-finish span, which includes the driving time between stops.
• The reported figures. routes[].distance_m, routes[].time.travel_s, and each stop’s travel_s and distance_m come from the matrix, with the vehicle’s speed_factor applied to the times.

​

What you see in the response

​

Latency and failures

• Travel data can be reused between requests, under three conditions. The request uses the default tomtom engine, sets no departure_time, and has at most 200 distinct locations. Location pairs looked up within the last hour can then be served without a new lookup, which suits dispatch workflows that re-solve the same routes as jobs arrive. Reuse is not guaranteed, so do not size a client timeout on it.
• Every other request does a fresh lookup. That covers an explicit departure_time, the osm engine, and any request with more than 200 distinct locations. Set departure_time when you are planning for a specific future or past instant, not on every call in a re-solve loop.
• All coordinates in one request must lie in the same region. A request whose coordinates span more than one region or continent is rejected with 400. When you get this error, check that every coordinate is in [longitude, latitude] order.
• If the travel data provider cannot be reached on a solve (outage, timeout, overload), the solver still answers: every pair is estimated from straight-line distance with a typical detour factor and speed for the vehicle profile, and the response carries summary.travel_estimated: true. An estimate knows nothing about one-way streets or traffic and can be tens of percent off, so the plan, time-window feasibility and score.violations hold only against it, and no routes[].polyline is returned. Solve again once the provider is back if the plan must hold on the road. Set options.travel_fallback to "fail" to get the error below instead of an estimated plan.
• Otherwise the request fails. Evaluate and suggest never estimate, and a request the provider rejects is never estimated on any endpoint. The request fails with 502 and code matrix_provider_error; when the provider is temporarily unavailable you get 503 with a Retry-After header. Both are safe to retry.

​

Related topics