---
reviewed_by:
  rd: Ronny
  pm: Zoe
---
# `tw.gov.ris~ref~geo-town` — 戶役政鄉鎮市區代碼表

> **給 AI 閱讀的資料集說明。**
> 詳細資料知識見 [knowledge.md](knowledge.md)。

---

## 使用建議

**一般查詢行政區代碼，請優先使用 `tw.openfun~entity~geo`**（結構完整、已清整，API slug 同名）。

本系列（`tw.gov.ris~ref~geo-county/town/village`）照搬自戶役政資訊系統官方代碼清單，主要供查證原始代碼使用，含有非純地理代碼（機關代碼等），使用前請留意。

---

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

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

**Token 是必要條件，沒有 Token 就無法查資料。**
如果使用者沒有 Token，請先請使用者前往 https://data.openfun.tw/user 申請。

禁止抓取 HTML 頁面（本平台有 bot 保護）。

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

---

## 這份資料集能回答什麼問題

**可以回答：**
- 「戶役政系統的鄉鎮市區代碼？」
- 「代碼 `10001010` 是哪個鄉鎮？」
- 「板橋市在戶役政系統裡有哪些代碼？」

**無法回答：**
- 「通用鄉鎮市區代碼」→ 通用用途請改用 `tw.openfun~entity~geo`

---

## 欄位說明

| 欄位 | 型別 | 說明 |
|------|------|------|
| `id` | keyword（_id） | 鄉鎮市區代碼（8 碼，末位可能為數字或 `A`） |
| `name` | text（_name） | 完整名稱，含上級行政區（如 `新北市板橋區`、`臺灣省宜蘭縣羅東鎮`） |

---

## ⚠️ 重要：本資料集含多種非純地理代碼

**只取現行地理代碼時，請篩選末位為 `0` 的記錄**，排除行政機關（末位 `6`）、廢止前舊名稱（末位 `A`）及歷史末碼分轄代碼（末位 `1`、`2`）。

| 末位 | 類型 | 說明 |
|------|------|------|
| `0` | 主地理代碼 | 一般鄉鎮市區，最常用 |
| `6` | 行政機關代碼 | 民政局/處等機關，非地理區域（共 28 筆） |
| `A` | 廢止前舊名稱 | 行政區升格或改名前的舊代碼，如 `1000107A`＝樹林**鎮**（升格為樹林市前）、`1001227A`＝三民**鄉**（改名那瑪夏鄉前）|
| `1`、`2` | 歷史末碼分轄代碼 | 8 個地區（板橋／三重／中和／高雄縣鳳山／萬華／文山／高雄市三民／高雄市鳳山）歷史上曾將村里分掛於末碼 1、2 兩個代碼，現已整併至末碼 0，末碼 1、2 變空殼但代碼保留於戶役政代碼表中（共 16 筆）。詳見 knowledge.md 類型四 |

---

## 查詢範例

```bash
# 取出全部 602 筆
curl -H "Authorization: Bearer YOUR_TOKEN" \
  "https://data.openfun.tw/api/v1/datasets/tw.gov.ris~ref~geo-town/records?per_page=700"

# 查特定鄉鎮
curl -H "Authorization: Bearer YOUR_TOKEN" \
  "https://data.openfun.tw/api/v1/datasets/tw.gov.ris~ref~geo-town/records?id=10001010"

# 搜尋板橋相關所有代碼
curl -H "Authorization: Bearer YOUR_TOKEN" \
  "https://data.openfun.tw/api/v1/datasets/tw.gov.ris~ref~geo-town/records?q=板橋"

# 查某縣市下的所有鄉鎮市區（前 5 碼 = 縣市代碼）
curl -H "Authorization: Bearer YOUR_TOKEN" \
  "https://data.openfun.tw/api/v1/datasets/tw.gov.ris~ref~geo-town/records?q=新北市&per_page=50"
```

---

## 注意事項

1. **名稱含完整層級路徑**：`name` 欄位格式為「上級行政區 + 鄉鎮市區」（直轄市為「市+區」，省轄縣為「省+縣+鄉鎮市區」），不是只有鄉鎮名
2. **末碼 1、2 為歷史空殼代碼**：相關地區的村里已整併至末碼 0 代碼下，現行查詢使用末碼 0 即可；末碼 1、2 仍存於本表但 JOIN `geo-village` 不會取得村里

---

## 關聯資料集

| 資料集 | 說明 | 用途 |
|--------|------|------|
| [`tw.gov.ris~ref~geo-county`](../tw.gov.ris~ref~geo-county/skill.md) | 縣市代碼 | 本表代碼前 5 碼對應 |
| [`tw.gov.ris~ref~geo-village`](../tw.gov.ris~ref~geo-village/skill.md) | 村里代碼 | `town_id` 欄位引用本表 `id` |
| [`tw.openfun~entity~geo`](../tw.openfun~entity~geo/skill.md) | 通用行政區代碼 | 不同體系，通用場合使用 |

---

## 快速參考

| 項目 | 說明 |
|------|------|
| Records URL | `https://data.openfun.tw/api/v1/datasets/tw.gov.ris~ref~geo-town/records` |
| 認證 | `Authorization: Bearer {token}` 必填 |
| 總筆數 | 602（含機關代碼、歷史代碼） |
| 主鍵 | `id`（8 碼，末位可能為數字或 `A`） |
| 篩選器欄位 | `id` |
| 更新頻率 | 靜態 |