# Find a dataset in the TerraLab catalogue

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

Search the TerraLab catalogue of open datasets by need or place, with each licence, coverage, size and the call that gets it.

| | |
| --- | --- |
| REST | `POST https://mcp.terra-lab.ai/v1/tools/find_datasets` |
| MCP tool | `find_datasets` on `https://mcp.terra-lab.ai/mcp` |
| Group | Data catalog |

## Request

```bash
curl -X POST https://mcp.terra-lab.ai/v1/tools/find_datasets \
  -H "Authorization: Bearer $TERRALAB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"land cover","area":{"place":"Kenya"}}'
```

```python
import os
import requests

response = requests.post(
    "https://mcp.terra-lab.ai/v1/tools/find_datasets",
    headers={"Authorization": f"Bearer {os.environ['TERRALAB_API_KEY']}"},
    json={
        "query": "land cover",
        "area": {
            "place": "Kenya",
        },
    },
    timeout=120,
)
response.raise_for_status()
print(response.json()["structuredContent"])
```

```javascript
const response = await fetch('https://mcp.terra-lab.ai/v1/tools/find_datasets', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.TERRALAB_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "query": "land cover",
    "area": {
      "place": "Kenya"
    }
  }),
});
const data = await response.json();
console.log(data.structuredContent);
```

Other valid request bodies:

```json
{"query":"administrative boundaries","area":{"place":"Indonesia"}}
```

```json
{"ids":["esa_worldcover"],"area":{"place":"Belgium"}}
```

## 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 | What the data is about, in a few words: "land cover", "flood hazard", "administrative boundaries", "population". Up to 200 characters. |
| `area` | object | No | The area: a bbox, or a place (name, address or coordinates) with an optional radius in metres. The place the user asks about, not the user's own location. |
| `area.bbox` | array of number | No | [west, south, east, north] in decimal degrees (WGS 84). Exactly 4 items. |
| `area.place` | string or object | No | A place name or address, or a point. |
| `area.radius_m` | number | No | Radius around the place in metres. From 1 to 100000. |
| `kind` | string | No | Keep one kind of dataset only. One of `"air_quality"`, `"basemap"`, `"biodiversity"`, `"boundaries"`, `"buildings"`, `"cadastre"`, `"climate"`, `"elevation"`, `"energy"`, `"extract"`, `"geology"`, `"hazards"`, `"health"`, `"hydrology"`, `"imagery"`, `"landcover"`, `"poi"`, `"population"`, `"settlements"`, `"soil"`, `"topographic_base"`, `"transport"`. |
| `ids` | array of string | No | Describe these dataset ids (from an earlier answer) instead of searching; with area, each gets its size estimate there. 0 to 20 items. |
| `limit` | integer | No | How many datasets to return. From 1 to 20. Default `5`. |
| `request_id` | string | No | An id request_data returned (dr_ and 10 characters): gives that data request's status instead of searching. Up to 40 characters. |

## 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 asks what data exists for a need or a place before getting it: "what land cover data do you have for Kenya?", "official district boundaries of Indonesia", "is there a flood hazard map for Romania?". Searches the TerraLab catalogue of 344 hosted open datasets (land cover, boundaries, hazards, population, elevation, soil, buildings, hydrology, climate) and about 2,800 datasets TerraLab only points to. Give query (a few words), and area (a country or a place) to keep only datasets covering it and to get a size estimate. Returns at most 20 datasets (5 by default), best first, each with its licence and attribution quoted from the catalogue, resolution, date, coverage, whether TerraLab hosts it, and the call that gets it (extract_dataset, extract_open_data or get_elevation). Read hosted first: hosted false means TerraLab does not serve that data, so give its page and offer request_data; never present it as available. An empty list means the catalogue has nothing for this need here, not that the data does not exist. Not for OpenStreetMap features of a place (use extract_open_data). Never use the user's current location unless they type it.


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