# 快速入門

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

有兩條路：從程式碼呼叫 REST API，或把 MCP 伺服器加入 AI 代理程式。兩者使用同一個帳號，並共用每月 100 次免費呼叫。

## 從程式碼呼叫 API

### 建立 API 金鑰

1. 前往 [terra-lab.ai/login](https://terra-lab.ai/zh-TW/login) 登入。帳號免費，不需要信用卡。
2. 開啟 [儀表板，MCP](https://terra-lab.ai/zh-TW/dashboard/mcp)，然後選擇 **Advanced**、**API keys**。
3. 為金鑰命名、接受 API 條款，然後按 **Create key**。
4. 請現在就複製金鑰：它以 `tlk_` 開頭，只會顯示一次。

請把它放在環境變數中，絕不要寫進程式碼：

```bash
export TERRALAB_API_KEY="tlk_your_key_here"
```

### 檢查金鑰

`GET /v1/me` 會回傳你的帳號，以及本月剩餘的呼叫次數。

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

回應 `401` 代表金鑰遺失、打錯或已被撤銷。

### 發出第一次工具呼叫

用 `find_places` 找出某個地址的座標：

```bash
curl -X POST https://mcp.terra-lab.ai/v1/tools/find_places \
  -H "Authorization: Bearer $TERRALAB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"12 rue de la Paix, Annecy"}'
```

```python
import os
import requests

response = requests.post(
    "https://mcp.terra-lab.ai/v1/tools/find_places",
    headers={"Authorization": f"Bearer {os.environ['TERRALAB_API_KEY']}"},
    json={"query": "12 rue de la Paix, Annecy"},
    timeout=120,
)
response.raise_for_status()
print(response.json()["structuredContent"])
```

```javascript
const response = await fetch('https://mcp.terra-lab.ai/v1/tools/find_places', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.TERRALAB_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ query: '12 rue de la Paix, Annecy' }),
});
const data = await response.json();
console.log(data.structuredContent);
```

回應是一個 JSON 物件：`structuredContent` 放著結果與它的 `sources`，`content` 是同一份結果的文字版，`isError` 則表示工具是否拒絕了這個請求。

### 繼續深入

- 用 [extract_open_data](https://terra-lab.ai/docs/api/extract_open_data) 擷取某個區域的建物和道路。
- 用 [get_elevation](https://terra-lab.ai/docs/api/get_elevation) 取得高程、剖面或等高線。
- 在 [API 參考](https://terra-lab.ai/docs/api)瀏覽全部 29 個工具。

## 把 TerraLab 加入 AI 代理程式

在 Claude Code 中，只要一行指令：

```bash
claude mcp add --transport http terralab https://mcp.terra-lab.ai/mcp
```

接著在 Claude Code 中執行 `/mcp`，並登入 TerraLab。Claude、ChatGPT、Cursor、Codex 和 VS Code 的做法，請見 [MCP 伺服器](https://terra-lab.ai/zh-TW/docs/mcp)。

你可以這樣問：「顯示里昂帕爾迪厄車站周圍 500 m 內的建物，並給我一份 GeoPackage。」

Source: https://terra-lab.ai/zh-TW/docs/quickstart · Updated 2026-10-27