Find places and addresses

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.

Request

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"}'

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"])

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:

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

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

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.

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

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.