---
reviewed_by:
  rd: Ronny
  pm: James
---
# 立法院 API v2 — `tw.openfun~api~legislation`

給 AI 閱讀的使用指引。人類可在 https://data.openfun.tw/datasets/tw.openfun~api~legislation 看到資料集說明。完整 API 文件：https://v2.ly.govapi.tw/swagger.yaml

---

## ⚠️ 開始之前（AI agent 必讀）

**Base URL**：`https://v2.ly.govapi.tw`
**認證**：不需要。此 API 完全公開，無需 Token 或帳號。
**分頁參數**：`page`（頁碼，從 1 開始）、`limit`（每頁筆數，預設 20）
**查詢參數語言**：此 API 使用中文參數名稱（例如 `?委員姓名=韓國瑜`），請勿翻譯成英文。

最簡查詢範例：
```bash
curl "https://v2.ly.govapi.tw/legislators?屆=11&limit=5"
```

禁止用 WebFetch 抓 HTML 頁面，請直接呼叫 API。

**當使用者要查詢委員發言文字時，必須先詢問並讓使用者選擇，再執行查詢：**

> 請問您需要哪種逐字稿？
>
> - **AI 逐字稿**（IVOD WhisperX 自動轉錄）：幾乎即時可取得，但準確率約八成，非官方，不適合正式引用
> - **官方公報逐字稿**（立法院公報）：100% 準確的官方記錄，但需等會議結束後 2–3 週才會發布
>
> 請選擇後我再為您查詢。

**等使用者回覆後再動作**，不可在未確認前自行假設並查詢其中一種。

---

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

**可以回答：**
- 第 N 屆有哪些立委？某黨籍的立委有哪些？
- 某位立委提過哪些法案？參與過哪些委員會會議？
- 某個法律目前版本是什麼？歷史修訂有哪些？
- 某次會議的議程和相關議案是什麼？
- 某議案的提案人、連署人、目前審議進度是什麼？
- 某位委員的質詢記錄
- **某位立委最近的發言逐字稿**（即時：IVOD 的 `transcript.whisperx`；官方：公報 `gazette_agenda_doc` 全文，準確但慢 2–3 週）
- **某場會議有哪些委員有公報發言紀錄**（→ 公報發言索引，`類別代碼=7`）
- **某位委員在某場會議是否有公報發言紀錄**（→ 先查發言索引確認，再取公報全文）
- **某次記名表決誰投贊成／反對／棄權**（→ `/votes`，含完整投票名單）
- **某位委員參與過哪些記名表決、各投了什麼立場**（→ `/votes?投票委員=` 或 `贊成=`／`反對=`／`棄權=`）

**無法回答：**
- 立委的財產申報（→ 另有財產申報資料集）
- 政治獻金收支（→ `tw.politics.campaign-finance`）
- 地方議會資料（本 API 只含中央立法院）
- 即時直播（IVOD 記錄已播出的影像，非即時）

---

## 資料來源與更新頻率

| 項目 | 說明 |
|------|------|
| 原始來源 | 立法院（data.ly.gov.tw） |
| API 服務 | 由歐噴維護（ly.govapi.tw） |
| 授權 | 立法院網站資料開放宣告 |
| 更新頻率 | 即時（與立法院官方資料同步） |
| 涵蓋範圍 | 第 1 屆至今（歷屆立委、議案、法律、公報等） |

---

## API 端點總覽

共 42 個端點，分 9 大類：

| 類別 | 主要端點 | 用途 |
|------|----------|------|
| 立委 | `GET /legislators` | 查立委列表，可篩屆別、黨籍、選區 |
| 立委 | `GET /legislators/{term}/{name}` | 查特定立委詳細資料 |
| 議案 | `GET /bills` | 查議案列表，可篩提案人、狀態、類別 |
| 議案 | `GET /bills/{billNo}` | 查特定議案詳情 |
| 委員會 | `GET /committees` | 查委員會列表 |
| 公報 | `GET /gazettes` | 查公報 |
| 質詢 | `GET /interpellations` | 查質詢記錄 |
| IVOD | `GET /ivods` | 查影像記錄（含 AI 逐字稿） |
| 法律 | `GET /laws` | 查現行法律 |
| 法律 | `GET /law_versions` | 查法律歷史版本 |
| 會議 | `GET /meets` | 查會議列表與議程 |
| 表決 | `GET /votes` | 查記名表決紀錄，可篩屆別、會議、投票委員、立場 |
| 統計 | `GET /stat` | 取得整體統計資料 |

完整端點清單見 Swagger：https://v2.ly.govapi.tw/swagger.yaml

---

## 常用查詢範例

### 查立委

```bash
# 第 11 屆所有立委
curl "https://v2.ly.govapi.tw/legislators?屆=11&limit=100"

# 第 11 屆民進黨立委
curl "https://v2.ly.govapi.tw/legislators?屆=11&黨籍=民主進步黨"

# 依姓名查詢
curl "https://v2.ly.govapi.tw/legislators?委員姓名=韓國瑜"

# 查特定立委（第 11 屆，韓國瑜）的詳細資料
curl "https://v2.ly.govapi.tw/legislators/11/韓國瑜"

# 查某立委提出的法案
curl "https://v2.ly.govapi.tw/legislators/11/韓國瑜/propose_bills"

# 查某立委出席的會議
curl "https://v2.ly.govapi.tw/legislators/11/韓國瑜/meets"
```

### 查議案

```bash
# 查議案列表（第 11 屆）
curl "https://v2.ly.govapi.tw/bills?屆=11&limit=20"

# 查特定提案人的議案
curl "https://v2.ly.govapi.tw/bills?提案人=韓國瑜&屆=11"

# 查已完成三讀的法律案（通過的法案）
curl "https://v2.ly.govapi.tw/bills?議案流程.狀態=三讀&議案類別=法律案&屆=11"

# 查正在委員會審查中的議案
curl "https://v2.ly.govapi.tw/bills?議案流程.狀態=交委員會審查&屆=11"

# 查特定議案詳情
curl "https://v2.ly.govapi.tw/bills/{billNo}"

# 查議案的相關會議
curl "https://v2.ly.govapi.tw/bills/{billNo}/meets"
```

### 查 IVOD 發言影像與 AI 逐字稿

想取得立委發言的文字內容，有兩種管道，請依需求選擇：

| | 公報逐字稿 | IVOD AI 逐字稿 |
|--|-----------|---------------|
| 來源 | 官方，立法院公報 | 非官方，WhisperX AI 自動轉錄 |
| 準確率 | 100%（官方記錄） | 約 80%，可能有辨識錯誤 |
| 取得時間 | 會後 2–3 週 | 幾乎即時 |
| API | `GET /gazette/{編號}/agendas` → `GET /gazette_agenda_doc/{議程編號}/txt` | `GET /ivods/{id}` → `transcript.whisperx` |

> **請使用者自行選擇**：需要官方正確版本請等公報；需要即時參考請用 IVOD AI 逐字稿，但須留意準確率約八成，不適合作為引用依據。

**IVOD AI 逐字稿查詢方式：**

```bash
# 查特定立委的發言影像列表（支援 屆、會期、委員名稱、日期 篩選）
curl "https://v2.ly.govapi.tw/ivods?委員名稱=沈伯洋&屆=11&會期=5&limit=20"

# 查特定 IVOD 詳情（含逐字稿）
curl "https://v2.ly.govapi.tw/ivods/{IVOD_ID}"
```

**`GET /ivods/{id}` 回應結構：**

| 欄位 | 說明 |
|------|------|
| `IVOD_ID` | 影像 ID |
| `IVOD_URL` | 立法院影音連結 |
| `委員名稱` | 發言委員姓名 |
| `日期` | 發言日期 |
| `會議名稱` | 所屬會議名稱 |
| `會議資料.會議代碼` | 對應的 meet id（可直接接 `/meets/{id}` 取會議詳情，勿需另行猜測） |
| `開始時間` / `結束時間` | 發言時間段 |
| `支援功能` | 若含 `"ai-transcript"` 表示有逐字稿 |
| `transcript.whisperx` | AI 逐字稿陣列，每筆含 `start`（秒）、`end`（秒）、`text` |
| `transcript.pyannote` | 說話者分離資料 |

**取得並格式化逐字稿：**

```bash
# 列表先篩出有逐字稿的發言（支援功能含 ai-transcript）
curl -s "https://v2.ly.govapi.tw/ivods?委員名稱=沈伯洋&屆=11&會期=5&limit=20" | \
  python3 -c "
import json, sys
data = json.load(sys.stdin)
for v in data['ivods']:
    if 'ai-transcript' in v.get('支援功能', []):
        print(v['IVOD_ID'], v['日期'], v['會議名稱'])
"

# 取得並輸出逐字稿全文
curl -s "https://v2.ly.govapi.tw/ivods/{IVOD_ID}" | \
  python3 -c "
import json, sys
data = json.load(sys.stdin)
segs = data['data']['transcript']['whisperx']
for seg in segs:
    m, s = divmod(int(seg['start']), 60)
    print(f'[{m:02d}:{s:02d}] {seg[\"text\"].strip()}')
"
```

> **注意**：不是所有 IVOD 都有逐字稿，請先確認 `支援功能` 含 `"ai-transcript"` 再取 `transcript.whisperx`。

---

### 查公報逐字稿（官方全文）

公報是立法院會議的**官方逐字記錄**，準確率 100%，但會後約 2–3 週才發布。

**端點說明：**

| 端點 | 說明 |
|------|------|
| `GET /gazette/{公報編號}/agendas` | 列出該冊公報所有議程，含各議程的全文下載 URL |
| `GET /gazette_agenda_doc/{議程編號}/txt` | 取得單一議程的純文字全文 |
| `GET /gazette_agenda_doc/{議程編號}/html` | HTML 版本（含格式） |
| `GET /gazette_agenda_doc/{議程編號}/parsed` | 結構化解析版本 |

> **注意**：`GET /gazettes` 的篩選欄位只支援 `公報編號` 和 `卷`，**無法直接以委員姓名篩選**。需先透過 IVOD 或 meets 取得會議代碼，再找公報編號，進入議程層取全文。

**完整流程（以查某委員最新公報發言為例）：**

```bash
# 步驟一：從 IVOD 取得該委員近期發言的委員會代號
curl -s "https://v2.ly.govapi.tw/ivods?委員名稱=徐巧芯&屆=11&會期=5&limit=10" | python3 -c "
import json, sys
data = json.load(sys.stdin)
for v in data['ivods']:
    mc = v.get('會議資料',{}).get('委員會代碼',[])
    print(v['日期'], v['會議資料'].get('會議代碼',''), '委員會代號:', mc)
"

# 步驟二：用 meets 列表一次找出有公報的場次，並直接取得 gazette_agenda_doc ID
# ⚡ meets 列表回應已包含 議事網資料（含公報連結），不需逐筆呼叫 /meets/{id}
# ⚡ 公報紀錄DOC 的 URL 含有 gazette_agenda_doc ID（格式 LCIDC01_{gazette_id}），
#    可直接跳到步驟三，不需再呼叫 /gazette/{id}/agendas
curl -s "https://v2.ly.govapi.tw/meets?委員會代號=15&屆=11&會期=5&limit=30" | python3 -c "
import json, sys, re
data = json.load(sys.stdin)
for m in data['meets']:
    code = m.get('會議代碼','')
    for item in m.get('議事網資料', []):
        for link in item.get('連結', []):
            if link.get('標題','') == '公報紀錄DOC':
                url = link.get('連結','')
                match = re.search(r'LCIDC01_(\d+_\d+)', url)
                if match:
                    doc_id = match.group(1)
                    print(code, m.get('日期',''), '→ gazette_agenda_doc ID:', doc_id)
"

# 步驟三：直接取得公報全文並擷取特定委員發言
# （直接用步驟二的 doc_id，不需呼叫 /gazette/{id}/agendas）
curl -s "https://v2.ly.govapi.tw/gazette_agenda_doc/{doc_id}/txt" | python3 -c "
import sys, re
text = sys.stdin.read()
# ⚠️ 公報 txt 的立委發言格式為「{姓}委員{名}：」，例如「徐委員巧芯：」
# 不是「徐巧芯委員：」或「徐巧芯：」，搜尋錯格式會找不到任何結果
pattern = r'徐委員巧芯[：:].+?(?=\n\S+委員\S+[：:]|\n主席[：:]|\n\S+部長[：:]|\n\S+局長[：:]|\n\S+署長[：:]|\n\S+次長[：:]|\Z)'
matches = re.findall(pattern, text, re.DOTALL)
for i, m in enumerate(matches, 1):
    print(f'--- 段落 {i} ---')
    print(m[:3000])
"
```

> **⚠️ 公報 txt 立委名稱格式有兩種，需同時處理：**
> - **一般中文姓名**：`{姓}委員{名}：`（例：`徐委員巧芯：`、`王委員定宇：`）
> - **長名／原住民名**：`{全名}委員：`（例：`伍麗華Saidhai Tahovecahe委員：`、`鄭天財Sra Kacaw委員：`）
>
> 同時比對兩種格式的 regex：
> ```python
> # 擷取「委員姓名」→「發言內容」
> # 需先確認委員全名（從 /legislators API 取得）再決定用哪種格式搜尋
> import re
> # 格式一（一般）：姓(1字) + 委員 + 名(1-4字)
> pattern1 = r'(\S)委員(\S{1,4})[：:]'
> # 格式二（長名）：全名（含英文）+ 委員
> pattern2 = r'(伍麗華Saidhai Tahovecahe|鄭天財Sra Kacaw)委員[：:]'
> ```

### 大規模公報分析（跨多場會議統計）

查詢整個會期所有委員會議的公報資料時，**用 meets 列表一次取得所有公報連結，不需逐筆呼叫 `/meets/{id}`**：

```python
import urllib.request, urllib.parse, json, re

# 一次取得該會期全部委員會議（含公報連結）
params = urllib.parse.urlencode({'屆': '11', '會期': '5', '會議種類': '委員會', 'limit': '200'})
with urllib.request.urlopen(f'https://v2.ly.govapi.tw/meets?{params}') as r:
    data = json.load(r)

# 從列表直接提取所有 gazette_agenda_doc ID（跳過 /meets/{id} 和 /gazette/{id}/agendas）
doc_ids = []
for m in data['meets']:
    for item in m.get('議事網資料', []):
        for link in item.get('連結', []):
            if link.get('標題') == '公報紀錄DOC':
                url = link.get('連結', '')
                match = re.search(r'LCIDC01_(\d+_\d+)', url)
                if match:
                    doc_ids.append(match.group(1))

print(f'共 {len(doc_ids)} 份公報文件')
# → 直接用 doc_ids 逐一取 /gazette_agenda_doc/{id}/txt 即可
```

### 查委員是否有公報發言紀錄（發言索引）

**發言索引**是每冊公報的末尾索引頁（`類別代碼=7`），列出該冊公報中每個議程項目的**發言者名單**與頁碼。

**何時使用發言索引 vs. IVOD → meets 流程：**

| 情境 | 建議做法 |
|------|---------|
| 確認某委員在某冊公報**是否有**發言 | ✅ 發言索引（出席 ≠ 發言，索引是唯一官方確認來源） |
| 查某冊公報所有議程的發言者清單 | ✅ 發言索引（一次掃完） |
| 取得某委員**最新**公報發言全文（已知委員，不確定是哪冊）| ⚡ IVOD → meets → 公報（更快，可直接篩委員姓名） |
| 取得**某場特定會議**的公報全文（已知 meet_id） | ⚡ meets → 議事網資料 → 公報（直接定位，最快） |

> **發言索引的優勢是精確性，不是速度**。需要掃多冊公報才能找到委員，適合「驗證有無發言」或「盤點發言場次」，不適合只是想快速取得全文。

**查詢流程**：先從發言索引確認委員是否發言，再取對應議程的公報全文。

```bash
# 步驟一：取得某冊公報的所有議程，找發言索引（類別代碼=7）
curl -s "https://v2.ly.govapi.tw/gazette/{公報編號}/agendas" | python3 -c "
import json, sys
d = json.load(sys.stdin)
for a in d['gazetteagendas']:
    if a['類別代碼'] == 7:
        print('案由:', a['案由'])
        for u in a.get('處理後公報網址', []):
            if u['type'] == 'txt':
                print(f'  txt (no={u[\"no\"]}): {u[\"url\"]}')
"

# 步驟二：讀取發言索引全文（可能有多個 doc，no=0,1,2...，逐一讀取）
curl -s "https://v2.ly.govapi.tw/gazette_agenda_doc/{doc_id}/txt"
```

**發言索引的內容格式**：

```
本期委員發言紀錄索引

立法院第11屆第5會期第X次會議紀錄

{議程案由}（頁次：XXX－XXX）

發言者
{委員甲}（主席）、{委員乙}、{委員丙}、...
```

**注意事項**：
- `處理後公報網址` 裡的 **doc ID**（如 `1153501_00012`）和 **agenda ID**（如 `1153501_00011`）是不同的序列，必須從 agenda 的 `處理後公報網址` 取，不可自行推算
- 一個 agenda 可能對應 `no=0,1,2` 多個 doc，需全部讀取才有完整索引
- `parsed` 端點對發言索引回傳空值，請使用 `txt`
- `GET /gazette_agendas?類別代碼=7` 不支援此 filter，必須先取特定公報的議程列表再篩

---

**`/gazette/{編號}/agendas` 回應的議程欄位：**

| 欄位 | 說明 |
|------|------|
| `公報議程編號` | 議程 ID，格式 `{公報編號}_{序號}` |
| `會議日期` | 字串陣列（例如 `["2026-04-27"]`） |
| `案由` | 會議摘要，可用來辨識是哪場會議 |
| `起始頁碼` / `結束頁碼` | 在整冊 PDF 中的頁碼範圍 |
| `處理後公報網址` | 陣列，含 `type`（html/tikahtml/txt/parsed）與 `url` |

---

### 查預算審查提案人（誰提案刪減或凍結某部會預算）

**核心觀念**：預算審查提案人資料只存在於委員會公報全文中，沒有獨立 API 欄位。需要：
1. 依預算年度找對應的立法院會期
2. 找審查該部會的委員會
3. 取得公報全文，解析「第X案」提案人

**預算年度 → 立法院會期 對照**

| 預算年度 | 對應審查會期 | 審查時間 |
|---------|------------|--------|
| N 年度預算 | 第X屆第Y會期（偶數） | (N-1)年 9–12 月 |
| 114年度 | 第11屆第2會期 | 2024年 9–12 月 |
| 113年度 | 第10屆第8會期 | 2023年 9–12 月 |
| 112年度 | 第10屆第6會期 | 2022年 9–12 月 |

規律：N年度預算 → 前一年下半年的偶數會期（預算多在 10–12 月通過）

**部會 → 審查委員會 對照**

| 部會 | 委員會 | 委員會代號 |
|------|--------|---------|
| 勞動部、衛生福利部、環境部 | 社會福利及衛生環境委員會 | `26` |
| 教育部、文化部 | 教育及文化委員會 | `22` |
| 經濟部、農業部、科技部（國科會）| 經濟委員會 | `19` |
| 財政部、金融監管 | 財政委員會 | `20` |
| 外交部、國防部 | 外交及國防委員會 | `35` |
| 交通部、數位部 | 交通委員會 | `23` |
| 法務部、司法院 | 司法及法制委員會 | `36` |
| 內政部 | 內政委員會 | `15` |

**完整查詢流程**

```python
import urllib.request, urllib.parse, json, re

# 步驟一：找該會期、該委員會的預算審查場次
params = urllib.parse.urlencode({'屆': '11', '會期': '2', '委員會代號': '26', 'limit': '50'})
with urllib.request.urlopen(f'https://v2.ly.govapi.tw/meets?{params}') as r:
    data = json.load(r)

# 篩選有「預算」且有「勞動部」的場次
target_meets = []
for m in data['meets']:
    evt = m.get('會議資料', [{}])[0].get('會議事由', '') if m.get('會議資料') else ''
    if '勞動部' in evt and '預算' in evt:
        target_meets.append((m['會議代碼'], m.get('日期', ''), evt[:60]))
        print(m['會議代碼'], evt[:60])

# 步驟二：從 meets 列表直接取 gazette_agenda_doc ID（不需逐筆呼叫 /meets/{id}）
doc_ids = []
for m in data['meets']:
    evt = m.get('會議資料', [{}])[0].get('會議事由', '') if m.get('會議資料') else ''
    if '勞動部' not in evt or '預算' not in evt:
        continue
    for item in m.get('議事網資料', []):
        for link in item.get('連結', []):
            if link.get('標題') == '公報紀錄DOC':
                match = re.search(r'LCIDC01_(\d+_\d+)', link.get('連結', ''))
                if match:
                    doc_ids.append(match.group(1))

# 步驟三：讀公報全文，找提案人
for doc_id in doc_ids:
    with urllib.request.urlopen(
        f'https://v2.ly.govapi.tw/gazette_agenda_doc/{doc_id}/txt'
    ) as r:
        text = r.read().decode('utf-8')

    # 公報提案格式有兩種：
    # 1. 「第X案是[委員]委員...」（在政府官員說明中帶出）
    # 2. 「提案人：[委員甲]　[委員乙]　...」（正式列於提案書頭）
    # 找含「刪」「凍」「減列」的提案段落
    lines = text.split('\n')
    for i, line in enumerate(lines):
        if re.search(r'刪|凍結|減列', line):
            # 往前找提案人
            context = '\n'.join(lines[max(0,i-3):i+2])
            proposers = re.findall(r'提案人[：:]\s*(.+)', context)
            if proposers:
                print(f'提案: {line[:60]}')
                print(f'提案人: {proposers[0]}')
```

> **公報中提案結果的關鍵詞**：
> - `刪減 / 減列 N 萬元` → 正式刪除預算
> - `凍結 / 併凍 N 萬元` → 凍結（條件解凍）
> - `改主決議` → 改為附帶決議，不影響金額
> - `保留送協商` → 交黨團協商
> - `通過` / `已簽署` → 已確認

---

### 查表決紀錄

立法院的**記名表決（roll call vote）**已有專屬端點 `GET /votes`，直接回傳結構化的投票名單，**不需再從公報 `/parsed` 解析**。涵蓋第 8–11 屆共 6,145 筆。

> **重要**：只收錄**記名表決**。
> - **黨團協商通過**（`完成協商`）、口頭或舉手表決的議案：不會出現在 `/votes`
> - 立法院**院長主持院會、原則上不投票**，故不會出現在投票名單中

**端點：**

| 端點 | 說明 |
|------|------|
| `GET /votes` | 表決列表，可篩 `屆`、`會議代碼`、`表決型態`、`投票委員`、`贊成`、`反對`、`棄權`、`公報文件代碼`、`表決時間` |
| `GET /votes/{id}` | 特定表決詳情，`id` 為 `表決代碼`（例 `1150101_00002_55`） |
| `GET /votes/{id}/meets` | 該筆表決所屬的會議 |

**常用查詢：**

```bash
# 第 11 屆所有記名表決
curl "https://v2.ly.govapi.tw/votes?屆=11&limit=20"

# 某次會議的所有表決
curl "https://v2.ly.govapi.tw/votes?會議代碼=院會-11-5-4"

# 某委員參與過的所有表決（含贊成/反對/棄權）
curl "https://v2.ly.govapi.tw/votes?投票委員=沈伯洋&屆=11"

# 某委員「投反對」的表決
curl "https://v2.ly.govapi.tw/votes?反對=黃國昌&屆=11"
```

**`/votes` 回應 `votes[]` 的欄位：**

| 欄位 | 說明 |
|------|------|
| `表決代碼` | 唯一識別碼（`id_fields`），可接 `/votes/{id}` |
| `屆` / `會議代碼` / `會議名稱` | 所屬屆別與會議 |
| `公報文件代碼` | 對應公報文件（可回查公報全文，例 `1151901_00002`） |
| `表決型態` | 例「記名表決」 |
| `表決議題` | 表決標的描述（如「討論事項第二案　台灣民眾黨黨團提議逕付二讀」） |
| `表決時間` | 表決發生時間 |
| `表決結果` | 物件，含 `出席人數`、`贊成人數`、`反對人數`、`棄權人數` |
| `投票委員` | 所有參與投票的委員姓名陣列 |
| `贊成` / `反對` / `棄權` | 各立場的委員姓名陣列 |

**取得單筆表決並印出立場：**

```python
import urllib.request, urllib.parse, json

params = urllib.parse.urlencode({'會議代碼': '院會-11-5-4'})
with urllib.request.urlopen(f'https://v2.ly.govapi.tw/votes?{params}') as r:
    data = json.load(r)

for v in data['votes']:
    res = v['表決結果']
    print(v['表決議題'].strip())
    print(f"  贊成 {res['贊成人數']} / 反對 {res['反對人數']} / 棄權 {res['棄權人數']}")
    print('  贊成:', '、'.join(v['贊成']))
    print('  反對:', '、'.join(v['反對']))
```

> **舊方法（仍可用，但不建議）**：早期需從 `GET /meets/{id}` → `公報發言紀錄[].html_files` → 把 `/html` 改 `/parsed` → 讀 `votes[]`。現已有 `/votes` 專屬端點，可直接以委員姓名或會議代碼篩選，無需此繞路。`/parsed` 端點對發言索引（`類別代碼=7`）回傳空值。

---

### 查法律

```bash
# 查現行法律列表
curl "https://v2.ly.govapi.tw/laws?法律狀態=現行&limit=20"

# 依主管機關查
curl "https://v2.ly.govapi.tw/laws?主管機關=教育部"

# 查特定法律
curl "https://v2.ly.govapi.tw/laws/{id}"

# 查法律歷史修訂版本
curl "https://v2.ly.govapi.tw/laws/{id}/versions"
```

### 查委員會召委

> **重要**：`/committees/{id}` 只有委員會基本資料（名稱、職掌），**不含召委名單**。
> 召委資料在 **meets 列表**的 `會議資料[].委員會召集委員` 欄位，無需另查 `/meets/{id}`。

每個委員會本會期有 2 位召委，跨多場取 unique 即可得到完整名單：

```python
# 查所有常設委員會的召委（一次掃完）
import urllib.request, urllib.parse, json, re

committees = [
    (15, '內政'), (19, '經濟'), (20, '財政'), (22, '教育及文化'),
    (23, '交通'), (26, '社會福利及衛生環境'), (35, '外交及國防'), (36, '司法及法制'),
]
for code, name in committees:
    params = urllib.parse.urlencode({'屆': '11', '會期': '5', '委員會代號': str(code), 'limit': '20'})
    with urllib.request.urlopen(f'https://v2.ly.govapi.tw/meets?{params}') as r:
        data = json.load(r)
    names = set()
    for m in data['meets']:
        for item in m.get('會議資料', []):
            raw = item.get('委員會召集委員', '')
            if raw:
                # 欄位格式如「馬文君委員」或「陳冠廷（115/05/18）馬文君（115/05/20）委員」
                found = re.findall(r'([\u4e00-\u9fff·‧]{2,6})(?:委員|\（)', raw)
                names.update(found)
    print(f'{name}委員會：{", ".join(sorted(names))}')
```

---

### 查會議

```bash
# 查第 11 屆第一會期（2 月至 5 月）院會
curl "https://v2.ly.govapi.tw/meets?屆=11&會期=1&會議種類=院會&limit=20"

# 查第 11 屆第二會期（9 月至 12 月）財政委員會會議
# ⚠️ /committees/{id}/meets 的 屆/會期 參數無效（filter 會被忽略）
# 需改用 /meets 並以 委員會代號 篩選（代號為整數）
curl "https://v2.ly.govapi.tw/meets?屆=11&會期=2&委員會代號=20&limit=100"

# 依日期查詢
curl "https://v2.ly.govapi.tw/meets?日期=2026-05-01"

# 查特定會議的議案
curl "https://v2.ly.govapi.tw/meets/{id}/bills"

# 查特定會議的質詢記錄
curl "https://v2.ly.govapi.tw/meets/{id}/interpellations"
```

### 查會議議事錄

**議事錄 ≠ 公報**：這兩者是不同資料，不要混淆。

| | 議事錄 | 公報（gazette） |
|--|--------|----------------|
| 更新速度 | 會後約 **1 週** | 會後約 **2–3 週** |
| 來源 | `meets` API 的 `議事錄` 欄位 | `/gazettes` API |
| 內容 | 完整會議記錄，含**結論**、出席委員、列席官員 | 完整**逐字稿** |

**如何判斷某場會議是否有議事錄：**

```bash
# 查特定會議詳情（id 格式如 委員會-11-5-36-11）
curl "https://v2.ly.govapi.tw/meets/{id}"
```

回應的 `data` 物件中有兩個管道：

**管道一：`議事錄` 欄位**（結構化資料，較完整）
- 存在且非空 → 表示有議事錄
- 包含：`出席委員`（array）、`列席官員`（string）、`主席`、`時間`、`地點`
- `html_file`：議事錄 HTML 全文 URL（可 WebFetch 讀取）
- `txt_file`：議事錄純文字 URL
- `source_url`：ppg.ly.gov.tw 原始頁面

**管道二：`議事網資料[].連結[]`**（部分會議另有連結）
- 檢查陣列中是否有 `標題 = "本次會議議事錄"` 的連結

```python
# 批次篩選有議事錄的會議（Python，避免 Windows curl 中文問題）
import urllib.request, urllib.parse, json

params = urllib.parse.urlencode({'屆': '11', '會期': '5', '委員會代號': '20', 'limit': '50'})
with urllib.request.urlopen(f'https://v2.ly.govapi.tw/meets?{params}') as r:
    data = json.load(r)

for meet in data['meets']:
    code = meet.get('會議代碼', '')
    # 方法：直接用 /meets/{id} 逐筆確認 議事錄 欄位
    with urllib.request.urlopen(f'https://v2.ly.govapi.tw/meets/{urllib.parse.quote(code)}') as r2:
        detail = json.load(r2).get('data', {})
    if detail.get('議事錄'):
        print(code, detail['議事錄'].get('html_file', ''))
```

### 分頁查詢

```bash
# 第 2 頁，每頁 50 筆
curl "https://v2.ly.govapi.tw/legislators?屆=11&page=2&limit=50"
```

回應格式：`{ "total": N, "page": 1, "limit": 20, "legislators": [...] }`（各類資料的陣列鍵名不同）

---

## 注意事項

### `GET /meets/{id}` 回應結構

回應格式為 `{ "data": { ... }, "relations": {...} }`，`data` 的主要欄位：

| 欄位 | 說明 |
|------|------|
| `會議代碼` | 格式：`{種類}-{屆}-{會期}-{委員會代號}-{次}`，例如 `委員會-11-5-36-11` |
| `會議種類` | `院會` / `委員會` / `聯席會議` |
| `委員會代號` | 整數陣列（例如 `[36]`） |
| `日期` | 字串陣列（跨天會議有多個日期） |
| `會議資料` | 陣列，含時間、地點、會議事由、召集委員、出席委員等 |
| `議事網資料` | 陣列，含各類連結（會議影片、公報紀錄、本次會議議事錄等） |
| `發言紀錄` | 陣列，含立委發言片段（meetingContent、legislatorNameList 等） |
| `議事錄` | 物件（有則表示議事錄已上線），含完整會議記錄與**結論**、出席委員、列席官員、html_file、txt_file；會後約 1 週公布 |

> **`議事錄` 欄位缺席或為 null = 議事錄尚未上線**，不代表沒有公報。

---

### 屆別與會期

台灣立法院目前為第 **11 屆**（2024 年 2 月起）。不帶屆別參數通常回傳所有屆別資料，資料量龐大，建議加上屆別過濾。

**會期對照**（每屆任期四年，每年兩個會期，一屆共 8 個會期）：

| 會期值 | 期間 | 規律 |
|--------|------|------|
| `1`、`3`、`5`、`7` | 2 月至 5 月底 | **奇數**會期 = 上半年 |
| `2`、`4`、`6`、`8` | 9 月至 12 月底 | **偶數**會期 = 下半年 |
| `0` | 不定期 | 臨時會 或 預備會議 |

> 委員每年 2 月 1 日、9 月 1 日起報到，由各黨團協商決定開議日期。例如第 11 屆第 5 會期（`會期=5`）即為 2026 年 2–5 月。

### 議案流程.狀態 常見值

`議案流程.狀態` 為精確比對，字串需**完全符合**。常見狀態值如下：

| 狀態值 | 說明 |
|--------|------|
| `一讀` | 院會朗讀標題，交付審查階段 |
| `交委員會審查` | 已交付常設委員會審查 |
| `二讀` | 進入院會逐條討論階段 |
| `三讀` | 已完成三讀（法律案、預算案通過的最終狀態） |
| `撤回` | 提案人撤回議案 |
| `不予審議` | 院會決議不予審議 |

> 注意：只有**法律案、預算案**須經三讀；其他議案僅需二讀。每屆立法委員任期屆滿時，未議決的議案（預決算及請願案除外）下屆不予繼續審議。

### 委員會代碼速查

委員會代號為**整數**，非英文縮寫。

| 代碼（整數） | 委員會名稱 | 類型 |
|------|-----------|------|
| `15` | 內政委員會 | 常設 |
| `35` | 外交及國防委員會 | 常設 |
| `19` | 經濟委員會 | 常設 |
| `20` | 財政委員會 | 常設 |
| `22` | 教育及文化委員會 | 常設 |
| `23` | 交通委員會 | 常設 |
| `36` | 司法及法制委員會 | 常設 |
| `26` | 社會福利及衛生環境委員會 | 常設 |
| `27` | 程序委員會 | 特種 |
| `28` | 紀律委員會 | 特種 |
| `29` | 修憲委員會 | 特種 |
| `30` | 經費稽核委員會 | 特種 |

### 其他注意事項

- **查詢參數為中文**：`?委員姓名=韓國瑜`。macOS/Linux 的 curl 可直接帶中文；**Windows 環境下 curl 不會自動 URL encode 中文參數**，參數會被忽略，建議改用 Python：
  ```python
  import urllib.request, urllib.parse, json
  params = urllib.parse.urlencode({'屆': '10', '會期': '7', '委員會代號': '20'})
  with urllib.request.urlopen(f'https://v2.ly.govapi.tw/meets?{params}') as r:
      data = json.load(r)
  ```
- **回應鍵名因端點而異**：`/legislators` 回傳 `legislators` 陣列；`/bills` 回傳 `bills` 陣列，以此類推。
- **免費公開**：不需要 Token，但請勿短時間內大量請求。
- **歷史資料**：議案和法律有完整歷史記錄，查詢時建議加屆別篩選縮小範圍。

---

## 相關應用

- [lawtrace.tw](https://lawtrace.tw) — 法律修訂歷程追蹤
- [dataly.openfun.app](https://dataly.openfun.app) — 立法院資料視覺化平台

---

## 快速參考

| 項目 | 說明 |
|------|------|
| Base URL | `https://v2.ly.govapi.tw` |
| 認證 | 不需要（完全公開） |
| 查詢參數語言 | 中文（不可翻譯成英文） |
| 分頁 | `?page=1&limit=20` |
| 完整文件 | https://v2.ly.govapi.tw/swagger.yaml |
| 主要資料類別 | 立委 / 議案 / 法律 / 會議 / 委員會 / 公報 / 質詢 / IVOD / 表決 |
| 目前屆別 | 第 11 屆（2024–） |
| 記名表決 | `GET /votes`（第 8–11 屆，可篩 `投票委員=`／`贊成=`／`反對=`／`棄權=`） |
| 奇數會期（1,3,5,7） | 2–5 月（上半年） |
| 偶數會期（2,4,6,8） | 9–12 月（下半年） |
| 會期=0 | 臨時會 / 預備會議 |
| 三讀完成 | `?議案流程.狀態=三讀`（法律案、預算案通過的最終狀態） |
| 財政委員會 | `?委員會代號=20` |
| 內政委員會 | `?委員會代號=15` |