# Select features by location

> 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 features of a layer that intersect a second layer, lie within it or lie within a distance of it, or those that do not.

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

## Request

```bash
curl -X POST https://mcp.terra-lab.ai/v1/tools/select_by_location \
  -H "Authorization: Bearer $TERRALAB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://mcp.terra-lab.ai/dl/geojson/TOKEN/buildings.geojson","with_url":"https://example.com/rivers.geojson","relation":"within_distance","distance_m":200}'
```

```python
import os
import requests

response = requests.post(
    "https://mcp.terra-lab.ai/v1/tools/select_by_location",
    headers={"Authorization": f"Bearer {os.environ['TERRALAB_API_KEY']}"},
    json={
        "url": "https://mcp.terra-lab.ai/dl/geojson/TOKEN/buildings.geojson",
        "with_url": "https://example.com/rivers.geojson",
        "relation": "within_distance",
        "distance_m": 200,
    },
    timeout=120,
)
response.raise_for_status()
print(response.json()["structuredContent"])
```

```javascript
const response = await fetch('https://mcp.terra-lab.ai/v1/tools/select_by_location', {
  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",
    "with_url": "https://example.com/rivers.geojson",
    "relation": "within_distance",
    "distance_m": 200
  }),
});
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). |
| `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, of any geometry. |
| `relation` | string | No | intersects (default), within (wholly inside one polygon of the second layer) or within_distance (needs distance_m). One of `"intersects"`, `"within"`, `"within_distance"`. |
| `distance_m` | number | No | For within_distance: the distance in metres (convert km or miles first). From 0.1 to 100000. |
| `invert` | boolean | No | Keep the features that do not match instead. |
| `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 the features of a layer chosen by where they are against a second layer: those that intersect it, lie wholly within one of its polygons, or lie within distance_m of it ("buildings within 200 m of a river", "parcels touching the road"), or with invert those that do not. Both layers can be an uploaded file, a link, inline GeoJSON or a TerraLab download link, up to 20,000 features each. Features keep their attributes and geometry unchanged. Returns the count selected, sample rows, a map and GeoJSON, KML, Shapefile zip, GeoPackage and CSV downloads. To cut features at the edge of an area, use clip_features. 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/select_by_location · Updated 2026-11-15