# Open, map and convert GIS data

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

Any GeoJSON, KML, KMZ, GPX, Shapefile, CSV or WKT read, checked, shown on a map and converted to another format.

| | |
| --- | --- |
| REST | `POST https://mcp.terra-lab.ai/v1/tools/open_gis_file` |
| MCP tool | `open_gis_file` on `https://mcp.terra-lab.ai/mcp` |
| Group | Map data |

## Request

```bash
curl -X POST https://mcp.terra-lab.ai/v1/tools/open_gis_file \
  -H "Authorization: Bearer $TERRALAB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text":"<kml xmlns=\"http://www.opengis.net/kml/2.2\"><Placemark><name>A</name><Point><coordinates>6.12,45.9</coordinates></Point></Placemark></kml>","convert_to":["gpx"]}'
```

```python
import os
import requests

response = requests.post(
    "https://mcp.terra-lab.ai/v1/tools/open_gis_file",
    headers={"Authorization": f"Bearer {os.environ['TERRALAB_API_KEY']}"},
    json={
        "text": "<kml xmlns=\"http://www.opengis.net/kml/2.2\"><Placemark><name>A</name><Point><coordinates>6.12,45.9</coordinates></Point></Placemark></kml>",
        "convert_to": ["gpx"],
    },
    timeout=120,
)
response.raise_for_status()
print(response.json()["structuredContent"])
```

```javascript
const response = await fetch('https://mcp.terra-lab.ai/v1/tools/open_gis_file', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.TERRALAB_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "text": "<kml xmlns=\"http://www.opengis.net/kml/2.2\"><Placemark><name>A</name><Point><coordinates>6.12,45.9</coordinates></Point></Placemark></kml>",
    "convert_to": [
      "gpx"
    ]
  }),
});
const data = await response.json();
console.log(data.structuredContent);
```

## Parameters

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

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `file` | object | No | A file uploaded in the conversation. |
| `file.download_url` | string | Yes |  |
| `file.file_id` | string | Yes |  |
| `file.file_name` | string | No |  |
| `file.mime_type` | string | No |  |
| `url` | string | No | A public http(s) link to the file. |
| `text` | string | No | The file content pasted as text (GeoJSON, KML, GPX, CSV or WKT). |
| `points` | array of object | No | Points to show and convert, with a name. The places the user asks about, not the user's own location. 0 to 5000 items. |
| `geojson` | object | No | A GeoJSON FeatureCollection, Feature or geometry in WGS 84, given as an object. |
| `title` | string | No | Name for the map and the output files when there is no file name. |
| `file_name` | string | No | Optional name of the file, used to name the outputs. |
| `convert_to` | array of string | No | Output formats wanted. |

## 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 shares or links a geographic file (GeoJSON, KML, KMZ, GPX track, zipped Shapefile, CSV with coordinates, WKT), pastes its content, or has a list of points or GeoJSON to put on a map, and wants to see it, understand it (format, coordinate system, extent, feature count, geometry types, fields, problems) or convert it to GeoJSON, KML, KMZ, GPX, Shapefile zip or CSV, for example a GPX track to a Shapefile or a KML to GeoJSON. Shapefile, GeoJSON, KML and CSV outputs open directly in QGIS. Also covers long tracks or point lists too big to write in the chat. Not for fetching new data about a place: that is extract_open_data. Not for styling layers, print layouts or chaining steps on the layers of a QGIS project the user has open: TerraLab AI Agent in QGIS does that. Files up to 50 MB. Never use the user's current location unless they type it. Download links build their file when opened; no file is saved. TerraLab reads the file or link to answer and keeps no copy.


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