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

​

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

​

Straight-line travel

{
  "problem": {
    "travel": { "engine": "straight_line", "speed_kmh": 50 },
    "vehicles": [
      {
        "id": "van-1",
        "shifts": [
          {
            "id": "wed",
            "from": "2026-07-01T08:00:00+02:00",
            "to": "2026-07-01T17:00:00+02:00",
            "start": { "location": [3.7174, 51.0543] }
          }
        ]
      }
    ],
    "jobs": [{ "id": "job-1", "location": [3.7250, 51.0500], "service_duration_s": 300 }]
  }
}

• Travel is the same in both directions, has no traffic, and is computed without a lookup, so it never fails and never falls back to an estimate. options.travel_fallback has no effect and summary.travel_estimated stays absent.
• Every vehicle drives at speed_kmh, so a vehicles[].profile other than car is a 400 pointing at that vehicle’s profile. To make one vehicle faster or slower, use its speed_factor.
• There is no road to draw, so options.polyline is a 400 pointing at /options/polyline, and stops carry no snapped_location.

​

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 osm engine (the default without a departure_time) or the tomtom engine, sets no departure_time, and has at most 200 distinct locations. Each engine’s travel data is reused only for that engine. 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.
• A straight_line request does no lookup at all, so its travel takes no noticeable time and cannot fail.
• Every other request does a fresh lookup. That covers an explicit departure_time, the tomtom_real_time 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.
• Any other failure to fetch travel times is answered with an estimate, whatever the cause: an outage, a timeout, overload or an error from the provider. Every pair is estimated from straight-line distance with a typical detour factor and speed for the vehicle profile, on solve, evaluate and suggest alike. Solve and evaluate responses carry summary.travel_estimated: true; a suggest response, which has no summary, carries a top-level travel_estimated: true. An estimate knows nothing about one-way streets or traffic, is the same in both directions, and can be tens of percent off, so the plan, time-window feasibility, score.violation_count and suggest’s insertions hold only against it. No routes[].polyline is returned, and snapped_location can be missing from the stops. Send the request again once the provider is back if the result must hold on the road.
• A solve or suggest with options.travel_fallback: "fail" fails instead. It returns 502 and code travel_provider_error; when the provider is temporarily unavailable you get 503 with a Retry-After header. Both are safe to retry. Evaluate has no such option.

​

Related topics