Calculate Route Matrix

The calculate_route_matrix MCP tool calculates travel times and distances between source and target locations.

Use this tool to compare multiple origin-destination pairs, select the nearest destination by travel cost, or prepare inputs for route optimization.

Tool name

calculate_route_matrix

Request URL

https://api.geoapify.com/v1/mcp?apiKey=YOUR_API_KEY

Input parameters

Name	Type	Required	Description
`sources`	array of objects	Yes	Matrix source locations with `lat` and `lon`. Provide between 1 and 1000 locations.
`targets`	array of objects	No	Matrix target locations with `lat` and `lon`. Defaults to `sources` when omitted.
`mode`	string	No	Travel or vehicle mode. Default: `drive`. See supported modes below.
`type`	string	No	Route preference: `balanced`, `short`, or `less_maneuvers`. Default: `balanced`.
`traffic`	string	No	Traffic model for motorized routing: `free_flow` or `approximated`. Default: `free_flow`.
`avoid`	array of strings	No	Up to three unique features to avoid: `tolls`, `highways`, and `ferries`.
`units`	string	No	`metric` or `imperial`. Default: `metric`.

Each location must contain a latitude from -90 to 90 and a longitude from -180 to 180. The number of sources multiplied by the number of targets must not exceed 1000. When targets is omitted, use the number of sources for both dimensions. The input schema does not allow additional properties.

Supported modes are drive, truck, light_truck, medium_truck, bus, motorcycle, scooter, bicycle, walk, and hike.

Example request

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "calculate_route_matrix",
    "arguments": {
      "sources": [
        { "lat": 52.52, "lon": 13.405 },
        { "lat": 52.51, "lon": 13.39 }
      ],
      "mode": "drive"
    }
  }
}

Response

The tool returns resolved source and target coordinates plus a sources_to_targets matrix. Each matrix cell can contain the distance and travel time for its source-target pair.

Example response

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{ ... }"
      }
    ],
    "structuredContent": {
      "sources": [
        { "lat": 52.52, "lon": 13.405 },
        { "lat": 52.51, "lon": 13.39 }
      ],
      "targets": [
        { "lat": 52.52, "lon": 13.405 },
        { "lat": 52.51, "lon": 13.39 }
      ],
      "sources_to_targets": [
        [
          { "distance": 0, "time": 0 },
          { "distance": 1800, "time": 420 }
        ],
        [
          { "distance": 1750, "time": 400 },
          { "distance": 0, "time": 0 }
        ]
      ],
      "units": "metric",
      "distance_units": "meters",
      "time_units": "seconds"
    },
    "isError": false
  }
}

Related tools

Calculate Route - calculate detailed routes, geometry, and instructions between ordered waypoints.
Geocode Address - convert addresses into matrix coordinates.

Related API

For direct HTTP API integration, see Route Matrix API.