# Find places and addresses

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

Coordinates of an address or place name, the address at a point, or a list of up to 100 addresses placed on a map with a CSV for QGIS.

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

## Request

```bash
curl -X POST https://mcp.terra-lab.ai/v1/tools/find_places \
  -H "Authorization: Bearer $TERRALAB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"12 rue de la Paix, Annecy"}'
```

```python
import os
import requests

response = requests.post(
    "https://mcp.terra-lab.ai/v1/tools/find_places",
    headers={"Authorization": f"Bearer {os.environ['TERRALAB_API_KEY']}"},
    json={
        "query": "12 rue de la Paix, Annecy",
    },
    timeout=120,
)
response.raise_for_status()
print(response.json()["structuredContent"])
```

```javascript
const response = await fetch('https://mcp.terra-lab.ai/v1/tools/find_places', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.TERRALAB_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "query": "12 rue de la Paix, Annecy"
  }),
});
const data = await response.json();
console.log(data.structuredContent);
```

Other valid request bodies:

```json
{"latitude":48.8584,"longitude":2.2945}
```

```json
{"addresses":["10 rue de Rivoli, Paris","Empire State Building, New York"],"title":"Visits"}
```

## Parameters

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

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `query` | string | No | One address or place name. The place the user asks about, not the user's own location. |
| `latitude` | number | No | Latitude for a reverse lookup. The place the user asks about, not the user's own location. From -90 to 90. |
| `longitude` | number | No | Longitude for a reverse lookup. The place the user asks about, not the user's own location. From -180 to 180. |
| `limit` | integer | No | For a single query: maximum number of matches. From 1 to 10. Default `5`. |
| `addresses` | array of string | No | A list of addresses to place, up to 100. The place the user asks about, not the user's own location. 1 to 100 items. |
| `text` | string | No | A list as text: one address per line, or CSV with an address column. The place the user asks about, not the user's own location. |
| `title` | string | No | For a list: map title, also used for file names. |

## 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 coordinates (latitude and longitude, GPS position) of an address or place name, the address at given coordinates, or wants places or addresses put, pinned or plotted on an interactive map, including a whole list of addresses (up to 100, pasted or as CSV with an address column). Worldwide, OpenStreetMap data; French street addresses are refined with the national address base. Shows the points on a map; for a list, gives a CSV with latitude and longitude added (opens directly in QGIS as a delimited text layer), plus KML and GeoJSON. Not for weather, opening hours, reviews, driving or travel directions and times, property prices, or general knowledge about a place (history, facts, travel advice): answer those without this tool. Never use the user's current location unless they type it. Download links build their file when opened; no file is saved. Never pass these links to open_gis_file.


Source: https://terra-lab.ai/docs/api/find_places · Updated 2026-10-27