---
reviewed_by:
  rd: Ronny
  pm: Zoe
---
# `tw.gov.ris~ref~geo-village` — 戶役政村里代碼表

> **給 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-village
API 端點：https://data.openfun.tw/api/v1/datasets/tw.gov.ris~ref~geo-village/records
認證方式（必填）：HTTP Header Authorization: Bearer {token}

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

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

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

---

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

**可以回答：**
- 「戶役政系統的村里代碼有哪些？」
- 「某鄉鎮下有哪些村里？」

**無法回答：**
- 「某村里的完整行政地址」→ 需 JOIN `tw.gov.ris~ref~geo-town` 取鄉鎮名稱
- 「通用村里代碼」→ 通用用途請改用 `tw.openfun~entity~geo`

---

## 欄位說明

| 欄位 | 型別 | 說明 |
|------|------|------|
| `village_id` | keyword（_id） | 村里代碼（11 碼）= town_id（8 碼）+ 村里序號（3 碼） |
| `town_id` | keyword | 所屬鄉鎮代碼（8 碼），對應 tw.gov.ris~ref~geo-town 的 `id` |
| `name` | text（_name） | 村里名稱（僅村里名，不含縣市與鄉鎮） |

---

## 查詢範例

```bash
# 查特定鄉鎮下的所有村里（town_id 篩選）
curl -H "Authorization: Bearer YOUR_TOKEN" \
  "https://data.openfun.tw/api/v1/datasets/tw.gov.ris~ref~geo-village/records?town_id=09007010&per_page=50"

# 查特定村里代碼
curl -H "Authorization: Bearer YOUR_TOKEN" \
  "https://data.openfun.tw/api/v1/datasets/tw.gov.ris~ref~geo-village/records?village_id=09007010001"

# 搜尋村里名稱（全文搜尋）
curl -H "Authorization: Bearer YOUR_TOKEN" \
  "https://data.openfun.tw/api/v1/datasets/tw.gov.ris~ref~geo-village/records?q=介壽村&per_page=20"
```

---

## 注意事項

1. **`name` 不含上層地名**：只有村里名（如 `介壽村`），完整地名需 JOIN `tw.gov.ris~ref~geo-town`
2. **village_id 結構**：前 8 碼即 `town_id`，後 3 碼為該鄉鎮內的流水序號
3. **含歷史村里**：7,770 筆涵蓋歷史與現行村里，非只有現行行政區
4. **資料量大**：7,770 筆，查詢時建議用 `town_id` 篩選特定鄉鎮，避免取出全部
5. **與 `tw.openfun~entity~geo` 村里代碼格式不同**：本資料集 `village_id` 為 **11 碼純數字**（如 `09007010001`），entity~geo 為 **`{8 碼}-{3 碼}`**（如 `09007010-001`）。村里序號相同但字串格式有別，跨資料集 JOIN 時需先統一

---

## 關聯資料集

| 資料集 | 說明 | 用途 |
|--------|------|------|
| [`tw.gov.ris~ref~geo-town`](../tw.gov.ris~ref~geo-town/skill.md) | 鄉鎮市區代碼 | `town_id` 欄位引用此表 |
| [`tw.gov.ris~ref~geo-county`](../tw.gov.ris~ref~geo-county/skill.md) | 縣市代碼 | 透過 geo-town 間接關聯 |
| [`tw.openfun~entity~geo`](../tw.openfun~entity~geo/skill.md) | 通用行政區代碼 | 不同體系，通用場合使用 |

---

## 快速參考

| 項目 | 說明 |
|------|------|
| Records URL | `https://data.openfun.tw/api/v1/datasets/tw.gov.ris~ref~geo-village/records` |
| 認證 | `Authorization: Bearer {token}` 必填 |
| 總筆數 | 7,770（含歷史村里） |
| 主鍵 | `village_id`（11 碼） |
| 篩選器欄位 | `village_id`、`town_id` |
| 更新頻率 | 靜態 |