---
reviewed_by:
  rd: tmonk
  pm:
---
# 戶役政系統代碼系列（`tw.gov.ris~ref~rscd*`）

> **給 AI 閱讀的使用指引。**
> 詳細資料知識見 [knowledge.md](knowledge.md)。

---

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

本文件說明的是一個**系列**，共 77 個資料集，slug 格式為 `tw.gov.ris~ref~rscd{代碼編號}`。
**查詢前必須先確認要用哪一個具體的資料集**（例如 `tw.gov.ris~ref~rscd3065`，不能直接用 `rscd_wildcard_`）。

API 端點格式：`https://data.openfun.tw/api/v1/datasets/tw.gov.ris~ref~rscd{代碼編號}/records`
認證方式（必填）：HTTP Header  Authorization: Bearer {token}

最簡查詢範例：
```bash
curl -H "Authorization: Bearer YOUR_TOKEN" \
  "https://data.openfun.tw/api/v1/datasets/tw.gov.ris~ref~rscd3065/records"
```

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

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

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

---

## 如何選擇正確的資料集

| 需要解讀的欄位類型 | 使用的資料集 |
|----------------|------------|
| 婚姻狀況 | `tw.gov.ris~ref~rscd3065` |
| 教育程度（戶籍） | `tw.gov.ris~ref~rscd0207` |
| 教育程度（役政） | `tw.gov.ris~ref~rscd4003` |
| 縣市代碼 | `tw.gov.ris~ref~rscd0102`（或改用 `tw.gov.ris~ref~geo-county`） |
| 省市縣市鄉鎮市區代碼 | `tw.gov.ris~ref~rscd0103` |
| 出生地代碼 | `tw.gov.ris~ref~rscd0104` |
| 原住民族別 | `tw.gov.ris~ref~rscd0220` |
| 役別（戶籍） | `tw.gov.ris~ref~rscd0204` |
| 役別（役政） | `tw.gov.ris~ref~rscd4017` |
| 軍種 | `tw.gov.ris~ref~rscd4004` |
| 體位 | `tw.gov.ris~ref~rscd4020` |
| 婚姻類別（登記） | `tw.gov.ris~ref~rscd3013` |
| 離婚種類 | `tw.gov.ris~ref~rscd3014` |
| 身分證處理狀況 | `tw.gov.ris~ref~rscd9007` |
| 戶別 | `tw.gov.ris~ref~rscd0201` |

完整清單見 [knowledge.md](knowledge.md)。

---

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

**可以回答：**
- 「戶籍資料中教育程度代碼 `01` 是什麼意思？」→ 查 rscd0207
- 「役政資料的體位代碼有哪些？」→ 查 rscd4020
- 「婚姻狀況代碼 `1` 代表未婚嗎？」→ 查 rscd3065
- 「出生地代碼 `01001` 對應到哪個地名？」→ 查 rscd0104

**無法回答：**
- 「台灣目前各縣市的人口」→ 這是統計資料，不是代碼表
- 「行政區的完整結構（含歷史沿革）」→ 用 `tw.openfun~entity~geo`
- 「戶籍登記的實際異動紀錄」→ 代碼表不含實際戶籍資料

---

## 欄位說明

所有 77 個資料集結構完全相同：

| 欄位 | 型別 | 說明 |
|------|------|------|
| `id` | keyword（`_id`） | 代碼值，格式因資料集而異（純數字、英文字母、或混合） |
| `內容` | text（`_name`） | 代碼對應的中文名稱 |

---

## API 呼叫範例

### 範例 1：取出某代碼表的所有值

```bash
# 婚姻狀況代碼（rscd3065，共 9 筆）
curl -H "Authorization: Bearer YOUR_TOKEN" \
  "https://data.openfun.tw/api/v1/datasets/tw.gov.ris~ref~rscd3065/records"
```

回應範例：
```json
{
  "total": 9,
  "records": [
    { "id": "1", "內容": "未婚" },
    { "id": "2", "內容": "有偶" },
    { "id": "3", "內容": "離婚" },
    { "id": "4", "內容": "喪偶" }
  ]
}
```

---

### 範例 2：查詢特定代碼的名稱

```bash
# 查教育程度代碼 "01" 的名稱（rscd0207）
curl -H "Authorization: Bearer YOUR_TOKEN" \
  "https://data.openfun.tw/api/v1/datasets/tw.gov.ris~ref~rscd0207/records?id=01"
```

用途：已知代碼值，要解讀其中文名稱時使用。

---

### 範例 3：取出大型代碼表（含分頁）

```bash
# 出生地代碼（rscd0104，共 2621 筆），分頁取得
curl -H "Authorization: Bearer YOUR_TOKEN" \
  "https://data.openfun.tw/api/v1/datasets/tw.gov.ris~ref~rscd0104/records?page=1&per_page=100"
```

用途：資料量較大的代碼表，建議加 `per_page` 控制每次回傳筆數。

---

## 注意事項與限制

1. **名稱相似但用途不同**：rscd0207（戶籍教育程度）與 rscd4003（役政教育程度）、rscd0204 與 rscd4017（役別），代碼體系各自獨立，不可混用。
2. **`id` 格式不統一**：數字、英文字母、補零與否各表不同，精確篩選時請確認目標欄位的實際格式再下查詢條件。
3. **地理代碼有更好的選擇**：若只需行政區代碼，建議改用 `tw.gov.ris~ref~geo-county/town/village` 或 `tw.openfun~entity~geo`，後者結構更完整。

---

## 關聯資料集

| 資料集 | 說明 | 用途 |
|--------|------|------|
| [`tw.gov.ris~ref~geo-county`](../tw.gov.ris~ref~geo-county/skill.md) | 戶役政縣市代碼 | rscd0102 的整理版 |
| [`tw.gov.ris~ref~geo-town`](../tw.gov.ris~ref~geo-town/skill.md) | 戶役政鄉鎮市區代碼 | rscd0103 的整理版 |
| [`tw.openfun~entity~geo`](../tw.openfun~entity~geo/skill.md) | 通用行政區代碼 | 地理查詢首選 |

---

## 快速參考

| 項目 | 說明 |
|------|------|
| Records URL | `https://data.openfun.tw/api/v1/datasets/tw.gov.ris~ref~rscd{代碼編號}/records` |
| 認證 | `Authorization: Bearer {token}` 必填 |
| 取得 Token | 免費申請：https://data.openfun.tw/user |
| 精確篩選 | `?id=代碼值`（`id` 為 keyword 欄位） |
| 全文搜尋 | `?q=關鍵字`（對 `內容` 欄位） |
| 分頁 | `?page=1&per_page=20`（預設 page=1, per_page=20） |
| 資料集總數 | 77 個（rscd0101 至 rscd9010） |
| 每表筆數 | 3（rscd0201）至 2621（rscd0104）不等 |