---
reviewed_by:
  rd: yo
  pm: Zoe
---
# 地政鄉鎮市區代碼表 — `tw.gov.moi.land~ref~cadastral-towns`

> **給 AI 閱讀的使用指引。**
> 人類可在 https://data.openfun.tw/datasets/tw.gov.moi.land~ref~cadastral-towns 看到同份內容的網頁版。
> 詳細資料知識見 [knowledge.md](knowledge.md)。

---

## ⚠️ 開始之前（AI agent 必讀，摘要也請保留這段）

資料集 slug：tw.gov.moi.land~ref~cadastral-towns
API 端點：https://data.openfun.tw/api/v1/datasets/tw.gov.moi.land~ref~cadastral-towns/records
認證方式（必填）：HTTP Header  Authorization: Bearer {token}

最簡查詢範例：curl -H "Authorization: Bearer YOUR_TOKEN" "https://data.openfun.tw/api/v1/datasets/tw.gov.moi.land~ref~cadastral-towns/records?per_page=20"

**Token 是必要條件，沒有 Token 就無法查資料。**
如果使用者沒有 Token，請停止並告訴使用者：「請先前往 https://data.openfun.tw/user 免費申請帳號與 API Token，取得後告訴我，我再幫您查詢。」

禁止抓取 HTML 頁面（本平台有 bot 保護，WebFetch 讀 HTML 頁面會失敗）。

授權標注：使用此資料產出的內容需標注「資料來源：歐噴資料庫（data.openfun.tw）／內政部地政司」

---

## 資料來源與更新頻率

| 項目 | 說明 |
|------|------|
| 原始來源 | 內政部地政司「地段查詢系統」（lisp.land.moi.gov.tw） |
| 授權 | 政府資料開放授權條款－第1版 |
| 更新頻率 | 不定期 |
| 涵蓋範圍 | 全國地政鄉鎮市區 |

---

## 這份資料集的定位

本表是**對照／橋接表**，單獨看「`AD01` = 松山區」沒有用途；會用到地政鄉鎮代碼，幾乎都是為了：

- **decode**：把地段代碼前 4 碼（或其他帶地政鄉鎮碼的資料）翻成鄉鎮市區名稱。
- **轉行政區代碼**：把地政鄉鎮轉成 8 碼行政區代碼，去串接一般行政區資料（注意 `IA01` 嘉義市、`OA01` 新竹市 對不到、為空，見 knowledge.md）。
- **盤點**：列出某事務所／縣市轄下有哪些鄉鎮市區（取得代碼後再 decode 或查地段）。

> 註：若只是要在地段表「依鄉鎮篩選」，`cadastral-sections` 可直接用 `鄉鎮名稱` 篩，不必先換成鄉鎮代碼。

以下問題本表**無法**回答：

- 「鄉鎮的人口、面積」（不在本資料集）
- 「某鄉鎮有哪些地段」（查 `cadastral-sections`，用 `鄉鎮名稱` 篩）

---

## 欄位說明

| 欄位名稱（API 參數） | 型別 | 說明 |
|---------------------|------|------|
| `鄉鎮代碼` | keyword（_id） | 4 碼鄉鎮市區唯一代碼 |
| `鄉鎮代碼.行政區代碼` | keyword（ref: tw.openfun~entity~geo） | 8 碼行政區代碼 |
| `鄉鎮市區名稱` | text（_name） | 鄉鎮市區名稱 |
| `鄉鎮市區代碼` | keyword | 2 碼鄉鎮市區代碼 |
| `縣市代碼` | keyword（篩選器、ref: tw.gov.moi.land~ref~cadastral-counties） | A–Z 單字母 |
| `縣市名稱` | keyword（篩選器） | 縣市名稱 |
| `事務所代碼` | keyword（篩選器、ref: tw.gov.moi.land~ref~cadastral-offices） | 2 碼事務所代碼 |
| `事務所名稱` | keyword（篩選器） | 事務所名稱 |

8 個欄位由上方 schema 自動列出。代碼結構（4 碼=事務所2碼+鄉鎮序2碼）與 `IA01/OA01` 對不到行政區代碼的結構性差異，見 [knowledge.md](knowledge.md)。

---

## API 呼叫範例

> 本表是中繼站，以下為各自獨立的查法，無先後關係（decode／轉行政區代碼／盤點轄區）。

### 範例 1：decode 地段代碼前 4 碼 → 鄉鎮市區名稱

```bash
# 地段代碼 AD01-0600 的前 4 碼 AD01
curl -H "Authorization: Bearer YOUR_TOKEN" \
  "https://data.openfun.tw/api/v1/datasets/tw.gov.moi.land~ref~cadastral-towns/records?鄉鎮代碼=AD01"
# → 松山區（鄉鎮代碼.行政區代碼 = 63000010）
```

### 範例 2：把地政鄉鎮轉成 8 碼行政區代碼，串接一般行政區資料

```bash
curl -H "Authorization: Bearer YOUR_TOKEN" \
  "https://data.openfun.tw/api/v1/datasets/tw.gov.moi.land~ref~cadastral-towns/records?鄉鎮代碼=AD01"
# → 取 鄉鎮代碼.行政區代碼 = 63000010，再帶入 tw.openfun~entity~geo 或人口／選舉等資料
# （IA01 嘉義市、OA01 新竹市 此欄為空，無法轉）
```

### 範例 3：盤點某事務所／縣市轄下的鄉鎮市區（取得後再 decode 或查地段）

```bash
# 某事務所（AD）轄下
curl -H "Authorization: Bearer YOUR_TOKEN" \
  "https://data.openfun.tw/api/v1/datasets/tw.gov.moi.land~ref~cadastral-towns/records?事務所代碼=AD&per_page=50"

# 某縣市（A 臺北市）全部
curl -H "Authorization: Bearer YOUR_TOKEN" \
  "https://data.openfun.tw/api/v1/datasets/tw.gov.moi.land~ref~cadastral-towns/records?縣市代碼=A&per_page=100"
```

---

## 關聯資料集

| 資料集 | 說明 | 用途 |
|--------|------|------|
| [`tw.gov.moi.land~ref~cadastral-counties`](../tw.gov.moi.land~ref~cadastral-counties/skill.md) | 縣市代碼 | 上層 |
| [`tw.gov.moi.land~ref~cadastral-offices`](../tw.gov.moi.land~ref~cadastral-offices/skill.md) | 事務所代碼 | 鄉鎮代碼前 2 碼 |
| [`tw.gov.moi.land~ref~cadastral-sections`](../tw.gov.moi.land~ref~cadastral-sections/skill.md) | 地段 | 地段代碼前 4 碼為鄉鎮代碼 |
| [`tw.openfun~entity~geo`](../tw.openfun~entity~geo/skill.md) | 一般行政區代碼 | 以 `鄉鎮代碼.行政區代碼` 串接 |

---

## 注意事項與限制

1. 鄉鎮代碼 4 碼 = 事務所 2 碼 + 鄉鎮序 2 碼；`鄉鎮市區代碼` 只是後 2 碼，需配事務所才唯一。
2. `IA01` 嘉義市、`OA01` 新竹市 的 `鄉鎮代碼.行政區代碼` 為空（地政不分區、行政區資料分區，結構性差異）。

---

## 快速參考

| 項目 | 說明 |
|------|------|
| Records URL | `https://data.openfun.tw/api/v1/datasets/tw.gov.moi.land~ref~cadastral-towns/records` |
| 認證 | `Authorization: Bearer {token}` 必填 |
| 取得 Token | 免費申請：https://data.openfun.tw/user |
| 精確篩選 | `?鄉鎮代碼=AD01`、`?事務所代碼=AD`、`?縣市代碼=A`、`?縣市名稱=臺北市`、`?事務所名稱=松山` |
| 全文搜尋 | `?q=松山` |
| 分頁 | `?page=1&per_page=20` |