# Travel times between many places

> Index of the TerraLab docs for agents: [llms.txt](https://terra-lab.ai/docs/llms.txt). Every docs page is also served as markdown: add .md to its URL.

Driving, walking or cycling distances and travel times from up to 25 origins to up to 25 destinations in one call, as a matrix with a map and a CSV.

| | |
| --- | --- |
| REST | `POST https://mcp.terra-lab.ai/v1/tools/get_travel_times` |
| MCP tool | `get_travel_times` on `https://mcp.terra-lab.ai/mcp` |
| Group | Terrain and routes |

## Request

```bash
curl -X POST https://mcp.terra-lab.ai/v1/tools/get_travel_times \
  -H "Authorization: Bearer $TERRALAB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"origins":["Lyon","Grenoble"],"destinations":["Annecy","Chambéry","Valence"],"mode":"driving"}'
```

```python
import os
import requests

response = requests.post(
    "https://mcp.terra-lab.ai/v1/tools/get_travel_times",
    headers={"Authorization": f"Bearer {os.environ['TERRALAB_API_KEY']}"},
    json={
        "origins": ["Lyon", "Grenoble"],
        "destinations": ["Annecy", "Chambéry", "Valence"],
        "mode": "driving",
    },
    timeout=120,
)
response.raise_for_status()
print(response.json()["structuredContent"])
```

```javascript
const response = await fetch('https://mcp.terra-lab.ai/v1/tools/get_travel_times', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.TERRALAB_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "origins": [
      "Lyon",
      "Grenoble"
    ],
    "destinations": [
      "Annecy",
      "Chambéry",
      "Valence"
    ],
    "mode": "driving"
  }),
});
const data = await response.json();
console.log(data.structuredContent);
```

Other valid request bodies:

```json
{"origins":[{"latitude":48.8566,"longitude":2.3522,"name":"Depot"}],"destinations":["Versailles","Saint-Denis","Créteil"],"mode":"driving"}
```

## Parameters

A JSON object in the request body; in an MCP client, the arguments of the tool call.

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `origins` | array of string or object | Yes | Start places or points: place names or {latitude, longitude}. 1 to 25 items. |
| `destinations` | array of string or object | Yes | End places or points. Repeat the origins for a matrix between every pair of the same places. 1 to 25 items. |
| `mode` | string | No | How the trips are travelled. One of `"driving"`, `"walking"`, `"cycling"`. Default `"driving"`. |
| `formats` | array of string | No | Download formats. Default `["csv","geojson"]`. |

## Response

`structuredContent` holds the result, `content` the same result as text for a model, and `isError` is `true` when the tool refused the request or failed; then `structuredContent.code`, `message` and `hint` say what to change.

```json
{
  "structuredContent": {
    "sources": [{ "name": "...", "licence": "...", "url": "..." }],
    "downloads": [{ "label": "...", "format": "...", "url": "...", "name": "..." }]
  },
  "content": [{ "type": "text", "text": "..." }],
  "isError": false
}
```

Every result lists its `sources` with their licence. File results come as `downloads`: each link builds its file when opened.

## Errors

A missing key answers `401`, an empty balance `402`, too many calls `429`. A call that fails or finds nothing is not counted. See [Errors and rate limits](https://terra-lab.ai/docs/errors).

## Description for agents

The text the server gives an agent to decide when to call this tool:

> Use this when the user wants driving, walking or cycling distances and travel times between many places at once: a distance or travel-time matrix from up to 25 origins to up to 25 destinations (625 pairs) in one call, for example from each warehouse to each store, or between every pair of towns in a list. Computed by Valhalla on the TerraLab server from the OpenStreetMap road network, with each road's typical speed. Returns one row per origin and destination pair (distance_km, duration_min; null with status no_route when no road links them, or not_computed when the routing engine did not answer in time: ask those pairs again), a map of the places and CSV, GeoJSON, KML or Shapefile downloads with a straight line per pair. At most 25 different place names per call, and at most 25 pairs farther apart than 400 km by car (200 km on foot or by bike) in a straight line. For the line along the roads of one trip use get_route. Not for live traffic, a departure time or public transport. Never use the user's current location unless they type it. Download links build their file when opened; no file is saved. The user opens the file in QGIS or any GIS: this server cannot load it into the user's own QGIS or any app on their computer. Never pass these links to open_gis_file: list every format the user needs in formats, in this one call.


Source: https://terra-lab.ai/docs/api/get_travel_times · Updated 2026-11-15