# Circle of a given radius around a place

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

A circle of a given radius around a place or a point, with its area and circumference, as a map and a GIS file.

| | |
| --- | --- |
| REST | `POST https://mcp.terra-lab.ai/v1/tools/circle_around_place` |
| MCP tool | `circle_around_place` on `https://mcp.terra-lab.ai/mcp` |
| Group | Layer operations |

## Request

```bash
curl -X POST https://mcp.terra-lab.ai/v1/tools/circle_around_place \
  -H "Authorization: Bearer $TERRALAB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"center":"Lyon Part-Dieu","radius_m":5000}'
```

```python
import os
import requests

response = requests.post(
    "https://mcp.terra-lab.ai/v1/tools/circle_around_place",
    headers={"Authorization": f"Bearer {os.environ['TERRALAB_API_KEY']}"},
    json={
        "center": "Lyon Part-Dieu",
        "radius_m": 5000,
    },
    timeout=120,
)
response.raise_for_status()
print(response.json()["structuredContent"])
```

```javascript
const response = await fetch('https://mcp.terra-lab.ai/v1/tools/circle_around_place', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.TERRALAB_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "center": "Lyon Part-Dieu",
    "radius_m": 5000
  }),
});
const data = await response.json();
console.log(data.structuredContent);
```

## Parameters

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

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `center` | string or object | Yes | The center, a place name or {latitude, longitude}. The place the user asks about, not the user's own location. |
| `radius_m` | number | Yes | The radius in metres (convert km or miles first). From 1 to 2000000. |
| `formats` | array of string | No | Download formats. Default `["geojson","kml"]`. |

## 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 circle of a given radius around a place or a point, as a map and a GIS file, with its area and circumference: "everything within 5 km of Lyon Part-Dieu". Not a travel-time or road-distance area (get_travel_area). Returns the figures, 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. 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/circle_around_place · Updated 2026-11-15