---
reviewed_by:
  rd: Ronny
  pm:
---
# 內政部人民團體立案資料 — `tw.gov.moi.grouptw~ref~civil-association`

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

---

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

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

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

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

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

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

---

## 資料來源與更新頻率

| 項目 | 說明 |
|------|------|
| 原始來源 | 內政部合作及人民團體司 |
| 授權 | 政府資料開放授權條款 1.0 |
| 更新頻率 | 每日 |
| 涵蓋範圍 | 內政部核准立案之全國性人民團體（社會團體、職業團體等） |
| 總筆數 | 約 27,689 筆 |

---

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

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

- 「某協會/學會/公會的立案狀態、理事長、會址？」
- 「目前還在運作的社會團體有哪些？」（以 `團體狀態=已立案` 篩選）
- 「某人現在擔任哪些人民團體的理事長？」（以 `q[理事長]=姓名` 搜尋）
- 「目前任期尚未屆滿的理事長有哪些？」（以 `理事長任期.結束` 日期篩選）
- 「某類型的人民團體共有幾個？」（以 `團體類型` 聚合）

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

- 「某人民團體是否有法人資格（法院法人登記）？」→ 請查 `tw.gov.judicial~ref~foundation-doc`（類別=2）
- 「某人民團體的理事、監事成員名單？」→ 本資料集只有理事長，完整名單在法院登記資料
- 「政黨資訊」→ 請查 `tw.gov.moi~ref~party`

> **重要**：本資料集記錄的是**內政部的立案資格**，不等於法人資格。部分人民團體僅有立案、未辦法院法人登記。查詢現況時請先以 `?團體狀態=已立案` 過濾。

---

## 欄位說明

| 欄位名稱（API 參數） | 型別 | 說明 |
|---------------------|------|------|
| `團體名稱` | text（_name） | 團體名稱 |
| `團體類型` | keyword（篩選器） | 團體類型 |
| `團體狀態` | keyword（篩選器） | 團體狀態 |
| `立案證書字號` | keyword（_id） | 立案證書字號 |
| `成立日期` | date | 成立日期 |
| `理事長` | keyword | 理事長 |
| `理事長屆次` | keyword | 理事長屆次 |
| `理事長任期` | keyword | 理事長任期 |
| `理事長任期.開始` | date | 理事長任期開始 |
| `理事長任期.結束` | date | 理事長任期結束 |
| `會址電話` | keyword | 會址電話 |
| `會址` | keyword | 會址 |
| `會址.縣市` | keyword（篩選器、ref: tw.openfun~entity~geo） | 會址所在縣市 |
| `會址.鄉鎮市區` | keyword（篩選器、ref: tw.openfun~entity~geo） | 會址所在鄉鎮市區 |

### 關鍵欄位補充說明

| 欄位 | 型別 | 重要說明 |
|------|------|---------|
| `立案證書字號` | keyword（_id） | 唯一識別碼；格式因年代而異（早期純數字，近年含年份代碼） |
| `團體名稱` | text（_name） | 全文搜尋：`?q=消費者保護` |
| `團體類型` | keyword（篩選器） | `社會團體`、`職業團體`、`國際辦事處`、`國際性民間團體` |
| `團體狀態` | keyword（篩選器） | `已立案`、`解散` 等；查現況必須加 `?團體狀態=已立案` |
| `理事長` | keyword（篩選器） | 現任理事長姓名；精確比對：`?理事長=王小明` |
| `理事長任期.開始` / `.結束` | date | 任期起訖日期（YYYY-MM-DD）；可判斷任期是否屆滿 |
| `會址` | text | 登記會址；欄位值內含括號異動日期（如「...（113年06月13日）」） |

---

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

### ⚠️ 預設包含已解散的歷史記錄

不加狀態篩選時，已解散的團體（約 2,087 筆）也會出現在結果中。查詢現況必須加：

```bash
?團體狀態=已立案
```

### ⚠️ 立案 ≠ 法人資格

本資料集記錄的是**內政部的立案資格**，不等於法院法人登記。部分團體僅有立案，未辦法院法人登記（法院登記屬自願性質）。

### ⚠️ 以姓名搜尋理事長可能命中同名同姓不同人

`?理事長=姓名` 以字串精確比對，常見姓名可能命中不同人，請提醒使用者交叉核對。

### ⚠️ 本資料集限內政部全國性團體

地方立案的人民團體（縣市政府社政部門核准）**不在本資料集**。

---

## API 呼叫範例

**Records URL：** `https://data.openfun.tw/api/v1/datasets/tw.gov.moi.grouptw~ref~civil-association/records`

### 範例 1：查詢現存社會團體（最常用）

```bash
curl -H "Authorization: Bearer YOUR_TOKEN" \
  "https://data.openfun.tw/api/v1/datasets/tw.gov.moi.grouptw~ref~civil-association/records?團體狀態=已立案&團體類型=社會團體&per_page=20"
```

### 範例 2：搜尋特定名稱的團體

```bash
curl -H "Authorization: Bearer YOUR_TOKEN" \
  "https://data.openfun.tw/api/v1/datasets/tw.gov.moi.grouptw~ref~civil-association/records?q=消費者保護&per_page=10"
```

### 範例 3：查詢某人擔任理事長的人民團體

```bash
curl -H "Authorization: Bearer YOUR_TOKEN" \
  "https://data.openfun.tw/api/v1/datasets/tw.gov.moi.grouptw~ref~civil-association/records?理事長=王小明&per_page=20"
```

> ⚠️ **必須提醒使用者**：以姓名搜尋理事長時，可能有同名同姓不同人的情況，請提示使用者交叉確認。

### 範例 4：查詢任期尚未屆滿的理事長（當前任期內）

```bash
# 以今日日期篩選任期結束日 > 今天
curl -H "Authorization: Bearer YOUR_TOKEN" \
  "https://data.openfun.tw/api/v1/datasets/tw.gov.moi.grouptw~ref~civil-association/records?團體狀態=已立案&sort=理事長任期.結束>&per_page=20"
```

### 範例 5：統計各類型團體數量

```bash
curl -H "Authorization: Bearer YOUR_TOKEN" \
  "https://data.openfun.tw/api/v1/datasets/tw.gov.moi.grouptw~ref~civil-association/agg?group_by=團體類型&團體狀態=已立案"
```

### 範例 6：統計各狀態分布

```bash
curl -H "Authorization: Bearer YOUR_TOKEN" \
  "https://data.openfun.tw/api/v1/datasets/tw.gov.moi.grouptw~ref~civil-association/agg?group_by=團體狀態"
```

---

## 關聯資料集

| 資料集 | 說明 | 用途 |
|--------|------|------|
| [`tw.gov.judicial~ref~foundation`](../tw.gov.judicial~ref~foundation/skill.md) | 法院法人主索引 | 確認某人民團體是否已辦理法院法人登記 |
| [`tw.gov.judicial~ref~foundation-doc`](../tw.gov.judicial~ref~foundation-doc/skill.md) | 法院法人登記詳細公告 | 查理事/監事完整名單、捐助方法、主事務所等法院登記資料 |
| [`tw.gov.moi~ref~party`](../tw.gov.moi~ref~party/skill.md) | 政黨立案資料 | 政治團體（政黨）另由此資料集記錄 |

---

## 注意事項與限制

1. **立案 ≠ 法人**：本資料集記錄內政部的立案資格，與法院法人登記是兩個獨立程序。有立案不代表有法人資格
2. **查詢現況請先過濾狀態**：資料集包含已解散的歷史紀錄，分析時請以 `?團體狀態=已立案` 過濾
3. **理事長姓名搜尋同名同姓風險**：`理事長` 為 text 欄位，以姓名搜尋時可能有同名同姓不同人，請提醒使用者交叉核對
4. **會址欄位含異動日期**：`會址` 欄位值內含括號日期（如「...（113年06月13日）」），為資料異動登錄日，非地址本身的一部分
5. **本資料集為內政部全國性團體**：地方立案的人民團體由各地方政府社政部門管理，不在本資料集內

---

## 快速參考

| 項目 | 說明 |
|------|------|
| Records URL | `https://data.openfun.tw/api/v1/datasets/tw.gov.moi.grouptw~ref~civil-association/records` |
| Agg URL | `https://data.openfun.tw/api/v1/datasets/tw.gov.moi.grouptw~ref~civil-association/agg` |
| 認證 | `Authorization: Bearer {token}` 必填 |
| 取得 Token | https://data.openfun.tw/user |
| 總筆數 | 約 27,689 筆 |
| 全文搜尋 | `?q=關鍵字`（搜尋團體名稱） |
| 理事長搜尋 | `?理事長=姓名`（精確比對） |
| 類型篩選 | `?團體類型=社會團體` |
| 狀態篩選 | `?團體狀態=已立案` |
| 分頁 | `?page=1&per_page=20` |
| Records 回應 | JSON，含 `total`、`page`、`per_page`、`records[]` |
| Agg 回應 | JSON，含 `total_records`、`total_groups`、`groups[].key`、`groups[].stats.count` |