# Convert coordinates

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

Coordinates converted between decimal degrees, degrees minutes seconds, UTM, MGRS, Lambert 93 or any EPSG code, with the format detected for you.

| | |
| --- | --- |
| REST | `POST https://mcp.terra-lab.ai/v1/tools/convert_coordinates` |
| MCP tool | `convert_coordinates` on `https://mcp.terra-lab.ai/mcp` |
| Group | Places |

## Request

```bash
curl -X POST https://mcp.terra-lab.ai/v1/tools/convert_coordinates \
  -H "Authorization: Bearer $TERRALAB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text":"48.8584, 2.2945\n45.8992 N 6.1294 E","target_epsg":"EPSG:2154"}'
```

```python
import os
import requests

response = requests.post(
    "https://mcp.terra-lab.ai/v1/tools/convert_coordinates",
    headers={"Authorization": f"Bearer {os.environ['TERRALAB_API_KEY']}"},
    json={
        "text": "48.8584, 2.2945\n45.8992 N 6.1294 E",
        "target_epsg": "EPSG:2154",
    },
    timeout=120,
)
response.raise_for_status()
print(response.json()["structuredContent"])
```

```javascript
const response = await fetch('https://mcp.terra-lab.ai/v1/tools/convert_coordinates', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.TERRALAB_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "text": "48.8584, 2.2945\n45.8992 N 6.1294 E",
    "target_epsg": "EPSG:2154"
  }),
});
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 |
| --- | --- | --- | --- |
| `text` | string | Yes | One coordinate per line, up to 1,000 lines. A label may follow the numbers. |
| `target_epsg` | string | No | Optional extra output system as an EPSG code. |
| `source_epsg` | string | No | Optional system the input is in, as an EPSG code, when it cannot be detected: Dutch RD EPSG:28992, Swiss LV95 EPSG:2056, British National Grid EPSG:27700, Poland 1992 EPSG:2180, UTM zone 32N EPSG:32632, ETRS89 or ED50 UTM EPSG:25830 / EPSG:23030. Leave out to detect each line. |

## 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 gives coordinates and wants them in another system or format: decimal degrees, degrees minutes seconds (GPS), UTM, MGRS, Lambert 93 (EPSG:2154, the French grid) or an EPSG code, for example Lambert 93 to WGS84 latitude and longitude, or GPS coordinates to UTM. The format of each line is detected automatically, including "lat, lon" or "lon, lat"; for a national grid the numbers alone cannot reveal (Dutch RD, Swiss LV95, British National Grid, Polish 1992, Belgian Lambert 72) or a UTM zone given apart from the numbers, set source_epsg. Converts one point or up to 1,000 lines to decimal degrees, DMS, UTM and MGRS (1 m), and optionally to an EPSG code, shows them on a map, and recommends the local projected CRS for working in QGIS. Returns a CSV and a GeoJSON download (both open directly in QGIS). Needs actual coordinates: to explain what a CRS, a projection or an EPSG code is, or to write conversion code, answer without this tool. Download links build their file when opened; no file is saved. Never pass these links to open_gis_file.


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