Calculate a source-to-target route matrix

Signed in? Open this endpoint in the dashboard playground, which uses your organization automatically. Signed out, use Try in Playground below with your API key.

POST

/routematrix

POST

/routematrix

Calculates travel distances and times from every source to every target (Valhalla sources_to_targets).

Send a JSON body with mode, sources and targets. Each location is [longitude, latitude].
sources_to_targets[i][j] describes the route from sources[i] to targets[j].
Repeat the same locations in sources and targets for a square all-to-all matrix.
distance or time is null when no route exists for a pair.
Size limit: 1 to 1000 sources and 1 to 1000 targets, each checked separately.

Deviation (approximated): Geoapify caps a regular call at 1,000 cells in total; this service caps sources and targets at 1000 each (see the sources field).

Deviation (ignored): traffic is accepted and ignored; durations are always free-flow.

Deviation (empty): response locations carry original_location only, no road-snapped location.

Not supported: modes transit and approximated_transit (400), the Geoapify per-pair and sum-of-distances limits, and asynchronous batch calls (/batch is not in v1).

curl -X POST 'https://api.data.graphitelab.ai/v1/routematrix?apiKey=YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"mode":"drive","sources":[{"location":[-86.158,39.768]}],"targets":[{"location":[-86.1,39.8]}]}'

curl -X POST 'https://api.data.graphitelab.ai/v1/routematrix?apiKey=YOUR_API_KEY' \  -H 'Content-Type: application/json' \  -d '{"mode":"drive","sources":[{"location":[-86.158,39.768]}],"targets":[{"location":[-86.1,39.8]}]}'

Authorization

queryapiKey<token>

Your API key from the dashboard, sent as ?apiKey=<key>.

Request Body

Route Matrix configuration. The request body must be JSON.

application/json

body

mode*string

Travel profile used to calculate speeds, access rules and road restrictions. drive represents a passenger car.

Deviation (unsupported): transit and approximated_transit are rejected with 400 (no transit data); they are not accepted for matrices on Geoapify either.

Value in"walk""hike""scooter""motorcycle""drive""light_truck""bicycle""mountain_bike""road_bike""bus""medium_truck""truck""truck_dangerous_goods""heavy_truck""long_truck"

sources*array<>

Origin locations. Each source produces one row in sources_to_targets.

Deviation (approximated): this service enforces 1 to 1000 sources and 1 to 1000 targets independently, not Geoapify's 1,000 total cells (sources x targets). Large matrices are computed in blocks of 150 x 150 (50 x 50 for scooter, motorcycle and bus), so very large requests are slow.

Items1 <= items <= 1000

targets*array<>

Destination locations. Each target produces one column in every sources_to_targets row. Same limits as sources.

Items1 <= items <= 1000

avoid?array<>

Road features, locations or polygons the router should avoid (up to 100 rules).

Itemsitems <= 100

traffic?string

Traffic model for motorized modes.

Deviation (ignored): accepted for compatibility; durations are always free-flow and the response always reports free_flow.

Default"free_flow"

Value in"free_flow""approximated"

type?string

Route preference. balanced balances time and distance; short prioritizes distance; less_maneuvers penalizes turns and is only valid for motorized modes (400 otherwise).

Default"balanced"

Value in"balanced""short""less_maneuvers"

max_speed?number

Maximum speed for driving, truck, motorcycle, scooter and bus modes. 10 to 252 km/h with units=metric, or 6.5 to 155 mph with units=imperial; outside that range returns 400. Ignored for walking and cycling modes.

Range6.5 <= value <= 252

units?string

Unit system for matrix distances. metric returns meters; imperial returns miles (3 decimals).

Default"metric"

Value in"metric""imperial"

Response Body

Matrix rows correspond to sources; columns to targets. Distances use the requested unit system, times are in seconds.

application/json

response

sources*array<>

targets*array<>

sources_to_targets*array<array<>>

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

units*string

Value in"metric""imperial"

distance_units*string

Value in"meters""miles"

mode*string

Value in"walk""hike""scooter""motorcycle""drive""light_truck""bicycle""mountain_bike""road_bike""bus""medium_truck""truck""truck_dangerous_goods""heavy_truck""long_truck"

type?string

Value in"balanced""short""less_maneuvers"

max_speed?number

Echo of the request value, present only when sent.

avoid?array<>

Echo of the request rules, present only when sent.

traffic?string

Always free_flow (see the request traffic deviation).

Value in"free_flow""approximated"

Example Request

curl -X POST 'https://api.data.graphitelab.ai/v1/routematrix' \
  -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
      ]
    }
  ]
}'

Example Request

curl -X POST 'https://api.data.graphitelab.ai/v1/routematrix' \  -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      ]    }  ]}'

Example ResponseSchema

{
  "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"
}

{  "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"}

Calculate a source-to-target route matrix

AuthorizationCopy Anchor Link

Request BodyCopy Anchor Link

Response BodyCopy Anchor Link

Authorization

Request Body

Response Body