# Road route between 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 route through 2 to 25 places, with distance and travel time per leg and the route line.

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

## Request

```bash
curl -X POST https://mcp.terra-lab.ai/v1/tools/get_route \
  -H "Authorization: Bearer $TERRALAB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"points":["Annecy, France","Chamonix-Mont-Blanc, France"],"mode":"driving"}'
```

```python
import os
import requests

response = requests.post(
    "https://mcp.terra-lab.ai/v1/tools/get_route",
    headers={"Authorization": f"Bearer {os.environ['TERRALAB_API_KEY']}"},
    json={
        "points": ["Annecy, France", "Chamonix-Mont-Blanc, France"],
        "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_route', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.TERRALAB_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "points": [
      "Annecy, France",
      "Chamonix-Mont-Blanc, France"
    ],
    "mode": "driving"
  }),
});
const data = await response.json();
console.log(data.structuredContent);
```

Other valid request bodies:

```json
{"points":["Lyon Part-Dieu","Vieux Lyon","Croix-Rousse, Lyon"],"mode":"walking"}
```

## Parameters

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

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `points` | array of string or object | Yes | Start, optional stops and destination, in travel order: place names or {latitude, longitude}. 2 to 25 items. |
| `mode` | string | No | How the route is travelled. One of `"driving"`, `"walking"`, `"cycling"`. Default `"driving"`. |
| `avoid_tolls` | boolean | No | Driving: avoid toll roads where a reasonable alternative exists. Default `false`. |
| `avoid_highways` | boolean | No | Driving or cycling: avoid motorways and highways where possible. Default `false`. |
| `avoid_ferries` | boolean | No | Avoid ferries where possible. Default `false`. |

## 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 the driving, walking or cycling route between 2 to 25 places or points in order: the distance and travel time along the roads and paths, per leg and in total, and the route line. Computed by Valhalla on the TerraLab server from the OpenStreetMap road network, with each road's typical speed. Options avoid tolls, highways or ferries. Returns the figures (distance_m, distance_km, duration_s, duration_min), a map of the line and GeoJSON, KML, GPX, Shapefile zip and GeoPackage downloads. Not for a straight-line distance (measure_distance or measure), live traffic, departure-time travel times, public transport or turn-by-turn navigation. Never use the user's current location unless they type it. Download links build their file when opened; no file is saved. Never pass these links to open_gis_file.


Source: https://terra-lab.ai/docs/api/get_route · Updated 2026-10-27