Route matrix

POST /v1/routematrix returns the distance and travel time for every source-to-target pair. Use it to rank candidates by drive time, build cost tables for dispatch, or feed an optimizer. Send the same locations as sources and targets for a square all-to-all matrix.

How it worksCopy Anchor Link

The gateway validates the body and calls Valhalla's sources_to_targets API. No geocoding engine is involved, so locations are plain coordinates, not addresses.

• Valhalla limits how many pairs one request may hold, so the gateway splits large matrices into blocks of 150 x 150 locations (50 x 50 for scooter, motorcycle and bus) and runs up to 4 blocks at a time.
• If Valhalla rejects a block because one pair is unroutable (no road near a point, unconnected regions), the gateway splits that block until it isolates the pair and reports it as null.
• Road data comes from OpenStreetMap, built into Valhalla tiles.

Quick startCopy Anchor Link

curl -s -X POST -H "Content-Type: application/json" -d '{"mode":"drive","sources":[{"location":[-86.158068,39.768403]},{"location":[-86.1581,39.7684]}],"targets":[{"location":[-86.1349,39.7817]},{"location":[-86.2,39.75]}]}' "https://api.data.graphitelab.ai/v1/routematrix?apiKey=$GRAPHITE_API_KEY"

{
  "sources": [
    { "original_location": [-86.158068, 39.768403] },
    { "original_location": [-86.1581, 39.7684] }
  ],
  "targets": [
    { "original_location": [-86.1349, 39.7817] },
    { "original_location": [-86.2, 39.75] }
  ],
  "sources_to_targets": [
    [
      { "distance": 2900, "time": 298, "source_index": 0, "target_index": 0 },
      { "distance": 4956, "time": 426, "source_index": 0, "target_index": 1 }
    ],
    [
      { "distance": 2907, "time": 299, "source_index": 1, "target_index": 0 },
      { "distance": 4963, "time": 427, "source_index": 1, "target_index": 1 }
    ]
  ],
  "units": "metric",
  "distance_units": "meters",
  "mode": "drive",
  "type": "balanced",
  "traffic": "free_flow"
}

ParametersCopy Anchor Link

The request is a JSON body. Each location is {"location": [longitude, latitude]}.

Full parameter reference

ResponseCopy Anchor Link

sources_to_targets[i][j] describes the route from sources[i] to targets[j].

This endpoint returns coordinates only, so there is no place_id, datasource or rank.

Differences from GeoapifyCopy Anchor Link

• approximated: the limit is 1000 sources and 1000 targets, checked separately. Geoapify caps a regular call at 1,000 cells in total. There are no per-pair or sum-of-distances limits.

• ignored: traffic is accepted and ignored. Durations are always free-flow.

• empty: sources and targets carry original_location only, with no road-snapped location.

• ignored (in avoid): green_zones, transfers and country_codes are accepted and have no effect.

Also not supported: transit and approximated_transit modes (400), and asynchronous batch calls (/batch is not in v1).

US and Canada notesCopy Anchor Link

Valhalla covers the US and Canada, and the examples run in Indianapolis and Montreal. Routing quality follows OpenStreetMap road coverage and restrictions.

More examplesCopy Anchor Link

A second 2 x 2 drive matrix, in Montreal.

curl -s -X POST -H "Content-Type: application/json" -d '{"mode":"drive","sources":[{"location":[-73.5673,45.5017]},{"location":[-73.58,45.51]}],"targets":[{"location":[-73.6,45.53]},{"location":[-73.55,45.49]}]}' "https://api.data.graphitelab.ai/v1/routematrix?apiKey=$GRAPHITE_API_KEY"

{
  "sources_to_targets": [
    [
      { "distance": 5855, "time": 540, "source_index": 0, "target_index": 0 },
      { "distance": 1944, "time": 153, "source_index": 0, "target_index": 1 }
    ],
    [
      { "distance": 5098, "time": 557, "source_index": 1, "target_index": 0 },
      { "distance": 4834, "time": 508, "source_index": 1, "target_index": 1 }
    ]
  ],
  "units": "metric",
  "distance_units": "meters",
  "mode": "drive"
}

Errors and limitsCopy Anchor Link

Limits: 1 to 1000 sources, 1 to 1000 targets, up to 100 avoid rules. Very large matrices are computed in blocks, so they are slow.