---
reviewed_by:
  rd: Ronny
  pm:
---
# 人事總處機關代碼 — `tw.gov.dgpa~ref~gov-org`

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

---

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

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

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

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

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

授權標注：使用此資料產出的內容需標注「資料來源：歐噴資料庫（data.openfun.tw）／行政院人事行政總處」

---

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

以下問題，這份資料集**可以回答**：

- 「教育部的機關代碼是多少？」
- 「機關代碼 A13000000G 是哪個機關？」
- 「行政院底下有哪些部會（層級 2 的機關）？」
- 「經濟部的機關代碼什麼時候改制？舊代碼是什麼？」
- 「這個機關代碼是現行還是已裁撤的？」

以下問題，這份資料集**無法回答**：

- 「教育部的 OID 碼是多少？」（需查 `tw.gov.moda~ref~oid`）
- 「投資審議司的機關代碼是多少？」（司、處等單位通常無獨立機關代碼，見注意事項）
- 「這個機關的統一編號是什麼？」（本資料集無統一編號欄位）

---

## 資料來源與更新頻率

| 項目 | 說明 |
|------|------|
| 原始來源 | 行政院人事行政總處（DGPA） |
| 更新頻率 | 按需更新（機關改制時） |
| 總筆數 | 約 17,388 筆（**含歷史裁撤機關**，2026-05 查詢） |

---

## 欄位說明

> API 查詢時使用欄位名稱作為 query 參數名稱。

| 欄位名稱（API 參數） | 型別 | 說明 |
|---------------------|------|------|
| `機關代碼` | keyword（_id） | 機關代碼 |
| `機關名稱` | text（_name） | 機關名稱 |
| `機關英文名稱` | text | 機關英文名稱 |
| `郵遞區號` | keyword | 郵遞區號 |
| `機關地址` | text | 機關地址 |
| `機關電話` | text | 機關電話 |
| `主管機關代碼` | keyword（ref: tw.gov.dgpa~ref~gov-org） | 主管機關代碼 |
| `傳真` | text | 傳真 |
| `機關生效日期` | date | 機關生效日期 |
| `機關裁撤日期` | date | 機關裁撤日期 |
| `機關層級` | keyword | 機關層級 |
| `裁撤註記` | keyword | 裁撤註記 |
| `新機關代碼` | keyword（ref: tw.gov.dgpa~ref~gov-org） | 新機關代碼 |
| `新機關生效日` | date | 新機關生效日 |
| `舊機關代碼` | keyword（ref: tw.gov.dgpa~ref~gov-org） | 舊機關代碼 |

### 關鍵欄位補充說明

| 欄位 | 重要說明 |
|------|---------|
| `機關代碼` | 10 碼英數字，末碼為檢查碼，同時也是 API 記錄的 `_id`。新制代碼首碼為英文字母（如 `A00000000A`），舊制為數字（如 `300000000A`） |
| `機關裁撤日期` | **此欄位為空 = 現行機關**；有日期 = 已裁撤 |
| `主管機關代碼` | 上級機關的機關代碼，指向同一資料集 |
| `新機關代碼` | 改制後的新代碼（舊記錄填寫） |
| `舊機關代碼` | 改制前的舊代碼（新記錄填寫） |
| `機關生效日期` | 此機關代碼的生效日期（ISO 格式 YYYY-MM-DD） |
| `機關層級` | 1＝院級、2＝部會級、3–4＝所屬機關 |

---

## 重要注意事項（查詢前必讀）

### ⚠️ 資料包含大量歷史裁撤機關，預設查詢會包含已裁撤的機關

本資料集總筆數約 17,388 筆，但**大部分為歷史裁撤機關**。查詢結果若不篩選，會摻雜已裁撤的代碼。

判斷方式：`機關裁撤日期` 為空（null）= 現行機關；有日期值 = 已裁撤。

> ⚠️ `機關裁撤日期` 為 date 型別，**無法直接用 `=空值` 篩選**。查詢後請在程式端過濾，或改用全文搜尋配合名稱後自行判斷。

### ⚠️ 名稱搜尋會同時比對到新舊機關

全文搜尋（`?q=教育部`）會同時回傳現行與歷史代碼。若只需現行機關，取回資料後以 `機關裁撤日期 === null` 過濾。

### 機關代碼是唯一可靠的精確查詢方式

名稱可能因改制而變動，機關代碼才是穩定的唯一識別碼。若需要取得特定機關的代碼，建議先用名稱全文搜尋，再以代碼做後續查詢。

---

## API 呼叫範例

**Records URL：** `https://data.openfun.tw/api/v1/datasets/tw.gov.dgpa~ref~gov-org/records`
**Agg URL：** `https://data.openfun.tw/api/v1/datasets/tw.gov.dgpa~ref~gov-org/agg`

### 依名稱搜尋機關（全文搜尋）

```bash
curl -H "Authorization: Bearer YOUR_TOKEN" \
  "https://data.openfun.tw/api/v1/datasets/tw.gov.dgpa~ref~gov-org/records?q=教育部&per_page=10"
```

⚠️ 全文搜尋結果**包含歷史裁撤機關**，請確認 `機關裁撤日期` 是否為空以判斷現行狀態。

---

### 依機關代碼直接取得單筆記錄

```bash
# 取得行政院（現行）
curl -H "Authorization: Bearer YOUR_TOKEN" \
  "https://data.openfun.tw/api/v1/datasets/tw.gov.dgpa~ref~gov-org/records/A00000000A"

# 取得經濟部（現行，2023-09-26 改制後）
curl -H "Authorization: Bearer YOUR_TOKEN" \
  "https://data.openfun.tw/api/v1/datasets/tw.gov.dgpa~ref~gov-org/records/A13000000G"

# 取得經濟部（舊代碼，已裁撤）
curl -H "Authorization: Bearer YOUR_TOKEN" \
  "https://data.openfun.tw/api/v1/datasets/tw.gov.dgpa~ref~gov-org/records/313000000G"
```

---

### 查詢院級機關（層級 1）

```bash
curl -H "Authorization: Bearer YOUR_TOKEN" \
  "https://data.openfun.tw/api/v1/datasets/tw.gov.dgpa~ref~gov-org/records?機關層級=1&per_page=20"
```

---

### 查詢某機關底下的所屬機關

```bash
# 查行政院（A00000000A）直轄的部會
curl -H "Authorization: Bearer YOUR_TOKEN" \
  "https://data.openfun.tw/api/v1/datasets/tw.gov.dgpa~ref~gov-org/records?主管機關代碼=A00000000A&per_page=50"
```

---

### 追蹤機關改制歷程

```bash
# Step 1：查舊代碼，取得「新機關代碼」
curl -H "Authorization: Bearer YOUR_TOKEN" \
  "https://data.openfun.tw/api/v1/datasets/tw.gov.dgpa~ref~gov-org/records/313000000G"
# → 新機關代碼: "A13000000G"，機關裁撤日期: "2023-09-26"

# Step 2：查新代碼確認現行資料
curl -H "Authorization: Bearer YOUR_TOKEN" \
  "https://data.openfun.tw/api/v1/datasets/tw.gov.dgpa~ref~gov-org/records/A13000000G"
# → 機關名稱: 經濟部，機關生效日期: "2023-09-26"，舊機關代碼: "313000000G"
```

---

### 統計各層級機關數量（agg 端點）

```bash
# 全資料集各層級機關數量（含歷史裁撤）
curl -H "Authorization: Bearer YOUR_TOKEN" \
  "https://data.openfun.tw/api/v1/datasets/tw.gov.dgpa~ref~gov-org/agg?group_by=機關層級"
```

回應格式：
```json
{
  "total_records": 17388,
  "groups": [
    { "key": "2", "stats": { "count": 850 } },
    { "key": "3", "stats": { "count": 5200 } },
    ...
  ]
}
```

### 查詢某機關底下直轄的子機關數量（agg）

```bash
# 統計行政院（A00000000A）各直轄機關各自底下的機關數量
curl -H "Authorization: Bearer YOUR_TOKEN" \
  "https://data.openfun.tw/api/v1/datasets/tw.gov.dgpa~ref~gov-org/agg?group_by=主管機關代碼&主管機關代碼=A00000000A"
```

---

## 關聯資料集

| 資料集 | 說明 | 用途 |
|--------|------|------|
| [`tw.gov.moda~ref~oid`](../tw.gov.moda~ref~oid/skill.md) | 政府機關 OID 碼 | 可透過 OID 資料集的 `OrgCode` 欄位找到對應的 DGPA 機關代碼 |

---

## 注意事項與限制

1. **資料包含歷史裁撤機關**：總筆數約 17,388 筆，含大量已裁撤機關。查詢「現行機關」時，務必加上判斷 `機關裁撤日期` 為空的條件（API 支援篩選，但須注意 `機關裁撤日期` 為 date 型別，無法直接用 `=` 篩選空值；可改用全文搜尋後自行過濾，或取得記錄後判斷 `機關裁撤日期` 是否為 null）。

2. **司、處等單位通常無獨立機關代碼**：DGPA 代碼原則上只到機關層級，非獨立機關的「單位」（如各部的司、局、處）通常不在此資料集中，或其代碼與上級機關相同。例如：
   - 經濟部投資審議司：無獨立代碼，OID 資料顯示其 `OrgCode` 也是 `A13000000G`（與經濟部本身相同）
   - 立法院公報處、議事處：立法院（`400000000A`）以下所有處室均無獨立機關代碼

3. **包含國營事業等非典型機關**：資料集含部分國營事業的訓練機構或管理處，如「榮民工程股份有限公司員工訓練中心」，這些多已裁撤，但仍在資料集中。

4. **`新機關生效日` 欄位格式不一致**：部分記錄以民國年格式（如 `"1120926"`）儲存，而非 ISO 日期格式。以 `機關生效日期` 欄位為主。

---

## 快速參考

| 項目 | 說明 |
|------|------|
| Records URL | `https://data.openfun.tw/api/v1/datasets/tw.gov.dgpa~ref~gov-org/records` |
| 認證 | `Authorization: Bearer {token}` 必填 |
| 取得 Token | https://data.openfun.tw/user |
| 依名稱搜尋 | `?q=關鍵字`（含歷史裁撤） |
| 依代碼精確查詢 | GET `.../records/{機關代碼}` |
| 篩選現行機關 | 取得資料後判斷 `機關裁撤日期 === null` |
| 篩選層級 | `?機關層級=1`（院級）、`?機關層級=2`（部會級） |
| 查子機關 | `?主管機關代碼={上級代碼}` |
| 分頁 | `?page=1&per_page=20` |
| Records 回應格式 | JSON，含 `total`、`page`、`per_page`、`records[]` |
| Agg 回應格式 | JSON，含 `total_records`、`total_groups`、`groups[].key`、`groups[].stats.count` |