# Measure distance, area, radius or buffer

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

Geodesic distance and bearing between places, the length of a line, the area and perimeter of a polygon, or a circle or buffer around a shape.

| | |
| --- | --- |
| REST | `POST https://mcp.terra-lab.ai/v1/tools/measure` |
| MCP tool | `measure` on `https://mcp.terra-lab.ai/mcp` |
| Group | Places |

## Request

```bash
curl -X POST https://mcp.terra-lab.ai/v1/tools/measure \
  -H "Authorization: Bearer $TERRALAB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"method":"distance","points":["Paris, France","Geneva, Switzerland"]}'
```

```python
import os
import requests

response = requests.post(
    "https://mcp.terra-lab.ai/v1/tools/measure",
    headers={"Authorization": f"Bearer {os.environ['TERRALAB_API_KEY']}"},
    json={
        "method": "distance",
        "points": ["Paris, France", "Geneva, Switzerland"],
    },
    timeout=120,
)
response.raise_for_status()
print(response.json()["structuredContent"])
```

```javascript
const response = await fetch('https://mcp.terra-lab.ai/v1/tools/measure', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.TERRALAB_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "method": "distance",
    "points": [
      "Paris, France",
      "Geneva, Switzerland"
    ]
  }),
});
const data = await response.json();
console.log(data.structuredContent);
```

Other valid request bodies:

```json
{"method":"radius","center":"Lyon Part-Dieu","radius_m":5000}
```

```json
{"method":"area","points":[{"latitude":45.9,"longitude":6.12},{"latitude":45.9,"longitude":6.13},{"latitude":45.91,"longitude":6.13}]}
```

## Parameters

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

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `method` | string | Yes | What to measure. One of `"distance"`, `"area"`, `"radius"`, `"buffer"`. |
| `geometry` | object | No | A drawn geometry as GeoJSON (Point, LineString, Polygon, MultiLineString or MultiPolygon, WGS 84 longitude, latitude), or a Feature holding one. |
| `geometry.type` | string | No |  |
| `geometry.coordinates` | array | No |  |
| `geometry.geometry` | object | No |  |
| `formats` | array of string | No | Download formats. Default `["geojson","kml"]`. |
| `points` | array of string or object | No | For distance (2+) and area (3+): points or place names in order. The place the user asks about, not the user's own location. 2 to 500 items. |
| `center` | string or object | No | For radius: the center, a point or a place name. The place the user asks about, not the user's own location. |
| `radius_m` | number | No | For radius and buffer: the distance in metres (convert km or miles to metres first). From 1 to 2000000. |

## 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 a straight-line (as the crow flies) distance between places with midpoint and bearing, the length of a drawn line, the area and perimeter of a polygon, a circle of a given radius around a place, or a buffer of a given width around a drawn line or polygon. Distances and areas are geodesic on the WGS 84 ellipsoid, buffers are built in a local equidistant projection; every figure states its unit (m, km, m², ha, km²). method "distance" takes 2 or more points or place names, or a line in geometry; "area" takes 3 or more points or a polygon in geometry; "radius" takes a center and radius_m; "buffer" takes a geometry and radius_m. Not a road or travel distance. Returns the numbers, a map and GeoJSON, KML, Shapefile zip or CSV downloads. Never use the user's current location unless they type it. Give the place as the user names it (place name, address or coordinates): this tool locates it, so find_places is not needed first. Download links build their file when opened; no file is saved. 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/measure · Updated 2026-10-27