Estimate the population of an area

A modelled estimate of the people living in a circle, a bounding box, a travel area or an administrative boundary, from the GHS-POP 2025 grid.

Request

curl -X POST https://mcp.terra-lab.ai/v1/tools/estimate_population \
  -H "Authorization: Bearer $TERRALAB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"area":{"place":"Gare de Lyon Part-Dieu","radius_m":1000}}'

import os
import requests

response = requests.post(
    "https://mcp.terra-lab.ai/v1/tools/estimate_population",
    headers={"Authorization": f"Bearer {os.environ['TERRALAB_API_KEY']}"},
    json={
        "area": {
            "place": "Gare de Lyon Part-Dieu",
            "radius_m": 1000,
        },
    },
    timeout=120,
)
response.raise_for_status()
print(response.json()["structuredContent"])

const response = await fetch('https://mcp.terra-lab.ai/v1/tools/estimate_population', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.TERRALAB_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "area": {
      "place": "Gare de Lyon Part-Dieu",
      "radius_m": 1000
    }
  }),
});
const data = await response.json();
console.log(data.structuredContent);

Other valid request bodies:

{"travel":{"start":"Nairobi Central railway station","minutes":15,"mode":"walk"}}

{"area":{"place":"Villeurbanne","level":"municipality"}}

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 asks how many people live in an area: "how many people live within 1 km of Lyon Part-Dieu?", "within 15 minutes' walk of Nairobi Central station", "population of the commune of Villeurbanne". Give exactly one of: area with a place and radius_m (a circle) or a bbox; area with a place and level (municipality, county, region, country) for its administrative boundary; or travel (start, minutes or km, mode walk, drive or bike) for the area reachable along the roads. Sums the GHS-POP 2025 grid (100 m cells, EC JRC, CC BY 4.0) over the polygon, or worldpop_1km with source. Returns the population rounded to 10, the density per km², the area, and the polygon used as a GeoPackage. This is a modelled estimate from satellite-derived built-up areas and census totals, not a census count: say so, and never present it as an official figure. Limits: 50,000 km² per call; travel at most 120 minutes or 200 km. 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.