# Clip features to an area or a layer

> 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 layer cut to an area: a place, a place with a radius, a bounding box or a second layer of polygons.

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

## Request

```bash
curl -X POST https://mcp.terra-lab.ai/v1/tools/clip_features \
  -H "Authorization: Bearer $TERRALAB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://mcp.terra-lab.ai/dl/geojson/TOKEN/buildings.geojson","area":{"place":"Annecy","radius_m":150}}'
```

```python
import os
import requests

response = requests.post(
    "https://mcp.terra-lab.ai/v1/tools/clip_features",
    headers={"Authorization": f"Bearer {os.environ['TERRALAB_API_KEY']}"},
    json={
        "url": "https://mcp.terra-lab.ai/dl/geojson/TOKEN/buildings.geojson",
        "area": {
            "place": "Annecy",
            "radius_m": 150,
        },
    },
    timeout=120,
)
response.raise_for_status()
print(response.json()["structuredContent"])
```

```javascript
const response = await fetch('https://mcp.terra-lab.ai/v1/tools/clip_features', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.TERRALAB_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "url": "https://mcp.terra-lab.ai/dl/geojson/TOKEN/buildings.geojson",
    "area": {
      "place": "Annecy",
      "radius_m": 150
    }
  }),
});
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 |
| --- | --- | --- | --- |
| `file` | object | No | A file uploaded in the conversation (GeoJSON, KML, KMZ, GPX, zipped Shapefile, CSV or WKT). |
| `file.download_url` | string | Yes |  |
| `file.file_id` | string | Yes |  |
| `file.file_name` | string | No |  |
| `file.mime_type` | string | No |  |
| `url` | string | No | A public http(s) link to the features, or a TerraLab download link from an earlier answer. |
| `geojson` | object | No | The features as a GeoJSON FeatureCollection, Feature or geometry in WGS 84 (longitude, latitude). |
| `area` | object | No | For clip: the area to keep, as a bbox or a place with a radius (its bounding box is used). The place the user asks about, not the user's own location. |
| `area.bbox` | array of number | No | [west, south, east, north] in decimal degrees (WGS 84). Exactly 4 items. |
| `area.place` | string or object | No | A place name or address, or a point. |
| `area.radius_m` | number | No | Radius around the place in metres. From 1 to 100000. |
| `with_file` | object | No | The second layer, uploaded in the conversation. |
| `with_file.download_url` | string | Yes |  |
| `with_file.file_id` | string | Yes |  |
| `with_file.file_name` | string | No |  |
| `with_file.mime_type` | string | No |  |
| `with_url` | string | No | A link to the second layer, or a TerraLab download link. |
| `with_geojson` | object | No | The second layer as GeoJSON in WGS 84. Only its polygons count. |
| `formats` | array of string | No | Download formats. All five by default. |
| `title` | string | No | Name for the map and the output files. |

## 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 to clip (cut) a layer to an area: a place, a place with radius_m or a bbox (its bounding box is used), or a second layer of polygons. The layer can be an uploaded file, a link, inline GeoJSON or a TerraLab download link. Up to 20,000 features and 100,000 vertices. Returns the feature count, a map and GeoJSON, KML, Shapefile zip, GeoPackage and CSV downloads. 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. TerraLab reads the file or link to answer and keeps no copy.


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