# Nearest feature and its distance

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

For each feature of a layer, the nearest feature of a second layer and the distance to it.

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

## Request

```bash
curl -X POST https://mcp.terra-lab.ai/v1/tools/find_nearest_features \
  -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://mcp.terra-lab.ai/dl/geojson/TOKEN/pois.geojson","join_fields":["name"]}'
```

```python
import os
import requests

response = requests.post(
    "https://mcp.terra-lab.ai/v1/tools/find_nearest_features",
    headers={"Authorization": f"Bearer {os.environ['TERRALAB_API_KEY']}"},
    json={
        "url": "https://mcp.terra-lab.ai/dl/geojson/TOKEN/buildings.geojson",
        "with_url": "https://mcp.terra-lab.ai/dl/geojson/TOKEN/pois.geojson",
        "join_fields": ["name"],
    },
    timeout=120,
)
response.raise_for_status()
print(response.json()["structuredContent"])
```

```javascript
const response = await fetch('https://mcp.terra-lab.ai/v1/tools/find_nearest_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",
    "with_url": "https://mcp.terra-lab.ai/dl/geojson/TOKEN/pois.geojson",
    "join_fields": [
      "name"
    ]
  }),
});
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. |
| `join_fields` | array of string | No | The fields of the nearest feature to copy, as nearest_<field>. Its name by default. |
| `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, for each feature of a layer, the nearest feature of a second layer and the distance to it: the closest school to each building, the nearest road to each point. Both layers can be an uploaded file, a link, inline GeoJSON or a TerraLab download link, up to 20,000 features each. Adds nearest_distance_m (geodesic on the WGS 84 ellipsoid, between the two closest points, 0 when they touch) and the chosen fields of the nearest feature as nearest_<field>. Returns the least, median and greatest distance, sample rows, a map and GeoJSON, KML, Shapefile zip, GeoPackage and CSV downloads. Not a road distance or travel time (get_travel_times). 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/find_nearest_features · Updated 2026-11-15