# Area reachable in a travel time

> 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.

The area reachable from 1 to 10 places within a travel time or a distance on the road network, driving, walking or cycling (isochrones).

| | |
| --- | --- |
| REST | `POST https://mcp.terra-lab.ai/v1/tools/get_travel_area` |
| MCP tool | `get_travel_area` 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_area \
  -H "Authorization: Bearer $TERRALAB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"starts":["Gare d'\''Annecy"],"minutes":[15,30],"mode":"walking"}'
```

```python
import os
import requests

response = requests.post(
    "https://mcp.terra-lab.ai/v1/tools/get_travel_area",
    headers={"Authorization": f"Bearer {os.environ['TERRALAB_API_KEY']}"},
    json={
        "starts": ["Gare d'Annecy"],
        "minutes": [15, 30],
        "mode": "walking",
    },
    timeout=120,
)
response.raise_for_status()
print(response.json()["structuredContent"])
```

```javascript
const response = await fetch('https://mcp.terra-lab.ai/v1/tools/get_travel_area', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.TERRALAB_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "starts": [
      "Gare d'Annecy"
    ],
    "minutes": [
      15,
      30
    ],
    "mode": "walking"
  }),
});
const data = await response.json();
console.log(data.structuredContent);
```

Other valid request bodies:

```json
{"starts":["Lyon Part-Dieu","Grenoble"],"km":[10,25],"mode":"driving"}
```

## Parameters

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

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `starts` | array of string or object | Yes | Start places or points: place names or {latitude, longitude}. 1 to 10 items. |
| `minutes` | array of number | No | Travel times in minutes, one polygon each. Leave out when km is given. 0 to 4 items. Default `[5,10,20]`. |
| `km` | array of number | No | Distances along the roads in km, instead of minutes. 0 to 4 items. |
| `mode` | string | No | How the area is travelled. One of `"driving"`, `"walking"`, `"cycling"`. Default `"driving"`. |

## 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 area reachable from 1 to 10 places within a travel time or a distance along the roads (an isochrone, catchment or service area): for example everything within 5, 10 and 20 minutes on foot from a station, or 30 km by car. Driving, walking or cycling, computed by Valhalla on the TerraLab server from the OpenStreetMap road network with each road's typical speed. Returns one polygon per start and value, with fields start, minutes or km, and mode, a map, and GeoJSON, KML, Shapefile zip and GeoPackage downloads. Up to 4 values, at most 120 minutes or 200 km. Not for a circle of a fixed radius (circle_around_place or measure), live traffic, a given 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. Never pass these links to open_gis_file.


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