# API reference

> 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 TerraLab REST API serves the same 29 tools as the MCP server, as HTTPS endpoints: each tool is a `POST` with a JSON body, the account endpoints are `GET`.

## Base URL

```text
https://mcp.terra-lab.ai
```

Send your API key as a Bearer token on every call except the two public documents. See [Authentication](https://terra-lab.ai/docs/authentication).

## Account and discovery

| Endpoint | Auth | What it returns |
| --- | --- | --- |
| `GET /v1/me` | Key | The account, its calls this month and today, its balance and its activation state. |
| `GET /v1/tools` | Key | Every tool with its input and output JSON Schema. |
| `GET /v1/openapi.json` | None | This reference as an OpenAPI 3.1 document: [https://mcp.terra-lab.ai/v1/openapi.json](https://mcp.terra-lab.ai/v1/openapi.json). |
| `GET /v1/meta/pricing` | None | The price grid as JSON: [https://mcp.terra-lab.ai/v1/meta/pricing](https://mcp.terra-lab.ai/v1/meta/pricing). |

Check your key and your remaining calls:

```bash
curl https://mcp.terra-lab.ai/v1/me \
  -H "Authorization: Bearer $TERRALAB_API_KEY"
```

```python
import os
import requests

response = requests.get(
    "https://mcp.terra-lab.ai/v1/me",
    headers={"Authorization": f"Bearer {os.environ['TERRALAB_API_KEY']}"},
    timeout=120,
)
response.raise_for_status()
print(response.json())
```

```javascript
const response = await fetch('https://mcp.terra-lab.ai/v1/me', {
  headers: {
    Authorization: `Bearer ${process.env.TERRALAB_API_KEY}`,
  },
});
const data = await response.json();
console.log(data);
```

```json
{
  "account": "3f9c0a1e7b2d4c6a8e0f1b3d",
  "auth": "key",
  "today": {
    "calls": 3,
    "limit": 100
  },
  "month": {
    "calls": 12,
    "included": 100,
    "resets_at": "2026-11-01T00:00:00.000Z"
  },
  "balance": {
    "currency": "EUR",
    "amount": 0,
    "micros": 0
  },
  "activation": {
    "first_call_at": null,
    "first_call_client": null
  }
}
```

An illustrative answer for a new account. `month.included` is the number of calls included this calendar month (UTC); later calls are taken from the balance. `today.limit` carries the same number for older clients.

## Tools

### Places

| Tool | What it gives |
| --- | --- |
| [Find places and addresses](https://terra-lab.ai/docs/api/find_places) | 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. |
| [Convert coordinates](https://terra-lab.ai/docs/api/convert_coordinates) | Coordinates converted between decimal degrees, degrees minutes seconds, UTM, MGRS, Lambert 93 or any EPSG code, with the format detected for you. |
| [Measure distance, area, radius or buffer](https://terra-lab.ai/docs/api/measure) | Geodesic distance and bearing between places, the length of a line, the area and perimeter of a polygon, or a circle or buffer around a shape. |

### Map data

| Tool | What it gives |
| --- | --- |
| [Extract open map data for an area](https://terra-lab.ai/docs/api/extract_open_data) | OpenStreetMap and Overture layers for any area: buildings, roads, addresses, points of interest, land use, water and more, as GIS files. |
| [Open, map and convert GIS data](https://terra-lab.ai/docs/api/open_gis_file) | Any GeoJSON, KML, KMZ, GPX, Shapefile, CSV or WKT read, checked, shown on a map and converted to another format. |
| [Buffer, merge, clip or simplify features](https://terra-lab.ai/docs/api/process_geometry) | One GIS operation on a set of features: buffer, union, dissolve, intersection, difference, clip or simplify, returned as a file. |

### Terrain and routes

| Tool | What it gives |
| --- | --- |
| [Elevation, profile and contour lines](https://terra-lab.ai/docs/api/get_elevation) | Elevation of points, a profile along a path, or a DEM, hillshade, slope and contour lines for an area, worldwide at 30 m. |
| [Road route between places](https://terra-lab.ai/docs/api/get_route) | Driving, walking or cycling route through 2 to 25 places, with distance and travel time per leg and the route line. |
| [Area reachable in a travel time](https://terra-lab.ai/docs/api/get_travel_area) | The area reachable from 1 to 10 places within a travel time or a distance on the road network, driving, walking or cycling (isochrones). |

### Imagery and land

| Tool | What it gives |
| --- | --- |
| [Satellite image of an area](https://terra-lab.ai/docs/api/get_satellite_image) | A recent Sentinel-2 image of an area in true colour, false colour or NDVI, or an IGN aerial photo in France, as a GeoTIFF. |
| [Forest type (natural, planted, plantation)](https://terra-lab.ai/docs/api/get_forest_type) | Whether a forest is natural, naturally regenerating, planted, a plantation or tree crops, mapped at 10 m for 2020. |
| [Estimate the population of an area](https://terra-lab.ai/docs/api/estimate_population) | 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. |

### France

| Tool | What it gives |
| --- | --- |
| [French cadastral parcel and zoning](https://terra-lab.ai/docs/api/french_parcel) | The French cadastral parcel at an address or point, its reference and area, and the urban plan zone that applies there. |
| [French building heights](https://terra-lab.ai/docs/api/french_building_heights) | Height in metres, floors, main use and year built of every building around an address or in a small area in France, from IGN BD TOPO. |
| [Natural risks at an address or a point](https://terra-lab.ai/docs/api/get_natural_risks) | Natural risks at an address or point: flood zones, clay, seismic zone, cavities and commune risks in France, river flood depth elsewhere. |

### Data catalog

| Tool | What it gives |
| --- | --- |
| [Find a dataset in the TerraLab catalogue](https://terra-lab.ai/docs/api/find_datasets) | Search the TerraLab catalogue of open datasets by need or place, with each licence, coverage, size and the call that gets it. |
| [Extract a hosted dataset for an area](https://terra-lab.ai/docs/api/extract_dataset) | A hosted dataset from the TerraLab catalogue cut to an area: a GeoTIFF or a vector file with its licence, or only the statistics. |
| [Ask TerraLab to add data it does not have](https://terra-lab.ai/docs/api/request_data) | Ask TerraLab to add geographic data the catalogue does not have yet, with what you need and up to five places where you need it. |

## OpenAPI

Import [https://mcp.terra-lab.ai/v1/openapi.json](https://mcp.terra-lab.ai/v1/openapi.json) into Postman, Insomnia, Bruno or a client generator. It is built from the tool schemas the server runs, so it is never behind the server.


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