# CCAPI 背景知識（給 AI Agent 用） 這份文件是給 AI Agent 讀的背景知識，目的是避免你用自己既有知識庫裡「議會」 「議員」「council」等詞的一般定義去理解這個 API，因為那些定義通常來自其他 國家的政治制度，跟台灣地方自治的實際運作不同。API 呼叫方式（endpoint、 參數）請見 `/skill.md`，這份只講資料本身的定義。 ## 這個 API 是什麼、不是什麼 - **是**：台灣「地方制度法」規範的地方議會——直轄市議會、縣（市）議會——的 開放資料（屆期、議員、會期、場次、委員會、逐字稿）。 - **不是**立法院（國會）：立法委員、國會的資料在另一個姊妹專案 `ly.govapi.tw`，資料完全不重疊，欄位設計相似但不是同一份資料，也不能 互相查詢。看到「議員」不要當成「立法委員」，看到「議會」不要當成「國會」 「Parliament」。 - **不是**鄉鎮市民代表會：地方制度法底下還有更基層的「鄉（鎮、市）民代表 會」（代表、主席／副主席），這個 API 目前不收錄，只到縣市層級。 - 中文的「議會」在其他情境可能泛指各種合議制機關，但在這個 API 裡專指 下面這張表的直轄市議會／縣（市）議會，範圍是明確界定的，不是泛稱。 ## 台灣地方自治的層級 | 層級 | 機關名稱 | 成員稱謂 | 主持人 | 本 API 是否收錄 | |---|---|---|---|---| | 直轄市 | 直轄市議會 | 議員 | 議長／副議長 | ✅ | | 縣（市） | 縣（市）議會 | 議員 | 議長／副議長 | ✅ | | 鄉（鎮、市） | 鄉（鎮、市）民代表會 | 代表 | 主席／副主席 | ❌ 未收錄 | ## 資料實體關係 ``` 議會（council） → 屆（term） → 議員（councilor） └→ 會期（session） → 場次（sitting） → 會議（meet） → 會議摘要（meet_note）／逐字稿（meet_transcript） 議會（council） → 委員會（committee） ← 不綁屆，跨屆存續 議會（council） → 行政機關（agency） ← 議會監督的縣市政府機關，不綁屆 ``` ## 容易跟自己既有知識搞混的地方 ### 議員（councilor） - 是地方議會選出的民選代表，**不是**立法委員（國會議員）。 - 「議長」「副議長」不是獨立的實體或角色欄位，而是議員資料裡 `職稱` = `議長`／`副議長` 的那幾筆記錄，每屆由議員互選產生，不是外部 派任、也不是終身職。 - 每人每屆各有一筆獨立記錄，同一人連任多屆會有多筆記錄；資料裡有 「人物代碼」欄位可以用來比對同一人跨屆的記錄，但 API 目前沒有現成的 「查某人所有屆期」endpoint，需要自己抓「人物代碼」相同的記錄。 - `黨籍` 欄位是政黨正式全銜（例：中國國民黨、民主進步黨），不是簡稱或 英文縮寫。 - `黨籍` 跟 `參選政黨` 是**兩種不同口徑**，不要混用：`黨籍` 是內政部名冊 上「目前」的黨籍（該筆記錄被抓取當下的狀態，任期中轉黨、退黨會反映在 這個欄位，之後重新抓取名冊會更新），`參選政黨` 是當選該屆時、登記參選 當下所屬的政黨（屬於該屆這筆記錄的固定歷史事實，不會隨後續轉黨而改變）。 同一人同一屆通常兩者相同，但議員任期中轉黨的案例兩者會不一致——這不是 資料錯誤，是兩個欄位本來就代表不同時間點的狀態，查「這個人現在是哪個黨」 用 `黨籍`，查「這個人是用哪個黨的身分選上這屆」用 `參選政黨`。 - 不是每筆記錄都代表「該屆選舉的正式當選人」：`當選狀態` 欄位會標記 `當選`／`遞補`（原當選人出缺後依規定遞補）／`補選當選`（因出缺另外 辦理補選），較舊的資料這個欄位可能是空值（尚未回溯建檔，不代表一定是 正常當選）。`選區別`／`選舉區號` 是選舉區資訊，`區域` 欄位則只是 所屬縣市名稱，兩者不要混用。 ### 候選人（candidate） - **不是**「議員」——`候選人` 收錄的是選舉的**所有登記參選人**，包含落選的 人，不是只有當選、實際擔任過議員的人。要查「這個人是不是議員」請查 `councilor`，不要用查得到 `candidate` 記錄來推論。 - 收錄的選舉不只議員：縣市議員／直轄市議員之外，也有**縣市長／直轄市長**選舉 （`參選職位` 欄位是「直轄市長」或「縣市長」，議員候選人沒有這個欄位， `議會代碼` 是監督該縣市政府的議會）、**村（里）長**選舉（`參選職位` 是「村里長」， 另有 `鄉鎮市區`／`鄉鎮市區代碼`／`村里` 欄位，`選區別` 是「鄉鎮市區＋村里」；收錄民國 99 年以後各次選舉的完整名冊與得票，公報政見陸續補上）、**鄉鎮市長**與**鄉鎮市民代表**選舉 （`參選職位` 是「鄉鎮市長」「鄉鎮市民代表」，直轄市的山地原住民區是「山地原住民區長」 「山地原住民區民代表」；有 `鄉鎮市區`／`鄉鎮市區代碼` 欄位，代表的 `選區別` 是選區名稱， 例：茂林區第01選舉區；公報政見陸續補上）、**總統副總統**選舉（`參選職位` 是「總統」「副總統」， `議會代碼` 是 ly，`搭檔` 是同組另一位的候選人代碼，得票數是整組的）、立法委員選舉，以及已停止運作的 國民大會代表（`議會代碼` na，85 年與 94 年任務型國大）、臺灣省議員與省長（`議會代碼` tpg，83 年）選舉。各種 選舉的補選、重行選舉也收錄（補選有 `補選`、`投票日` 欄位）；議員選舉在選舉公報收錄範圍之前的 （直轄市議員 83～95 年、縣市議員 87～94 年）只有名冊與得票。即將舉行的選舉（115 年九合一）先收錄 中選會公告的候選人登記名冊（`登記階段` 為 true、代碼以 `REG-` 開頭，還沒有號次、政見）， 正式候選人名冊與選舉公報公布後換成正式資料。同一人在不同選舉的 紀錄用 `人物代碼` 串連（例：先當立委、後選市長的人，兩次參選是同一個人物代碼）。 在單一議會子網域只查得到該議會範圍的參選紀錄，要看一個人完整的參選史請用 all 子網域。 - 資料來源是選舉公報（政見/學經歷/相片），**目前只回溯到民國 98 年 （2009）**，更早期的公報幾乎都是純掃描圖、沒有文字層，不在這批資料裡—— 查不到一個人更早的參選紀錄不代表他沒參選過。 - `候選人代碼` 用來 join `councilor` 的 `參選代碼`／`人物代碼`（同一套代碼 體系）；查無此代碼代表沒有比對到候選人名單（約 3%），但學經歷/政見等 內容仍然是好的，只是不能拿來 join。 - **學歷／經歷／政見有沒有可用文字要看對應的 `學歷來源`／`經歷來源`／`政見來源`， 不能只看欄位本身是否有值**：`=text` 是公報 PDF 文字層直接抽出來的； `=text-garbled` 時欄位確實有值但是亂碼（來源 PDF 字型缺 ToUnicode CMap 造成），不可當文字用；`=cell-image-vision` 是來源沒比對到候選人名冊、 整格裁圖後改用 AI 視覺模型辨識出來的文字（不是 PDF 文字層，但仍可當文字 用，只是抽取方式不同、準確度可能略低於文字層——可能省略裝飾性文字/ QR code 等，取捨細節見該筆的 `note` 欄位）；完全沒有這個欄位時代表該 欄位是圖片或空白。`cell-image-vision` 這批候選人同時沒有比對到候選人 代碼裡的選舉代碼／行政區代碼，ccapi 匯入時會從候選人代碼反解出來，才能 正常查詢「同選區得票比較」。`=manifesto-image-vision`（政見欄位最常見 的來源）是政見整欄印成一張圖時，AI 視覺模型直接辨識整張圖得出的文字； `=page-image-vision` 是整頁都是掃描圖、逐頁辨識出來的文字，這兩種可信 度判斷方式跟 `cell-image-vision` 相同。 - `得票排名`／`得票率` 只有縣市議員／直轄市議員的資料才有（來源另外 join 中選會逐投開票所得票明細，取縣市層級總得票數計算），且只回溯到 民國 83 年（1994）左右，比候選人公報涵蓋的年份更早一點但仍不完整。 - `人物代碼`（跟 `councilor` 的「人物代碼」是同一套代碼體系，當選過的人 兩邊代碼相同）可以查出同一人歷次參選紀錄，包含落選的次數——`councilor` 完全沒有落選者的資料，要查一個人選了幾次、贏過幾次，只能靠這個欄位串 `candidate` 自己的記錄，不能只看 `councilor` 有沒有資料。 - **判斷是否當選請用 `當選` 欄位（來自中選會當選註記），不要用「這個候選人 代碼是否存在於 `councilor` 資料」來推論**：`councilor` 來源如果議員任期 中辭職，資料會直接消失整筆記錄，會把「當選但後來離職」誤判成「沒有 當選」（已知案例：李彥秀 111 年台北市議員選舉最高票當選，但 `councilor` 完全沒有這筆記錄）。`當選` 欄位不受這個問題影響，是選舉當下的正式結果。 ### 行政機關（agency） - 議會**監督**的縣市政府機關（目前只有縣市，不含中央政府），一個議會一棵樹： 最上層是縣市政府本身（`分類=縣市政府`），底下依 `分類` 分成「一級內部單位」 （縣市政府的內部單位，例：縣政府的民政處、主計處，沒有自己的機關代碼）、 「一級外部單位」（縣市政府直屬、有自己機關代碼的機關，例：警察局；直轄市的 一級機關幾乎都屬於這類）、「二級機關」（一級機關底下的獨立機關，`上層代碼` 指向所屬的一級機關）、「其他單位」（學校、戶政／地政事務所、區公所、鄉鎮市 公所與代表會、衛生所等）。 - `排序` 是縣市政府網站上組織架構的呈現順序，代表該縣市自己認定的位階順序， 列出機關時請依這個欄位排序，不要依名稱或代碼排。 - `機關代碼` 是行政院人事行政總處機關代碼。`代碼` 去掉開頭的「議會代碼-」 就是會議逐字稿（`meet_transcript`）的 `對應代碼`（`對應代碼類型=機關` 時）， 縣市政府內部單位也是同一套（例：`hsz-376580000A-U130000` 對應逐字稿裡 新竹市政府交通處的發言），可以用來查某個機關的官員在議會答詢的紀錄。 - 縣市政府的 `歷任首長` 是中選會歷屆縣市長／直轄市長選舉的當選人（只有正式 選舉，不含罷免後的補選、代理）。其他機關的 `首長紀錄` 是從會議逐字稿彙整 「誰以什麼職稱在議會答詢過」（各屆的職稱、次數、第一次與最後一次答詢日期）， **不是官方人事資料**，可能包含代理首長，也可能漏掉沒在議會答詢過的首長。 ### 屆（term） - 每個議會的屆次是**各自獨立計算**，從該議會設立時的第 1 屆起算。不同 議會同樣寫「第 14 屆」，對應到的西元年份完全不同，不能拿來跨議會比較 時間點。 - 屆與屆之間不一定緊密銜接，行政區劃調整、制度變革都可能造成中斷。 ### 會期（session）vs 場次（sitting） - 「會期」是一段期間（定期會／臨時會／成立大會），例如「第14屆第7次定期 會」，本身沒有逐日細節。 - 「場次」才是會期裡逐日的排程，通常一天拆成上午／下午兩筆。 - 這兩層都**不是**單一會議的逐字內容，真正的會議內容在「會議」（meet） 底下的「會議摘要」（meet_note）／「逐字稿」（meet_transcript）——通常 一個場次對應一筆會議，但遇到分組審查（例如臺北市委員會同一天平行 審查）時，一個場次可能對應多筆會議，各自是獨立的委員會審查，不能假設 場次跟會議是1對1。 - **已知的分類缺口**：部分議會有不屬於「定期會／臨時會／成立大會」三種 分類的特殊大會——例如台北市議會的「就職典禮」（議員宣誓就職＋正副議長 選舉，於成立大會前一天召開）、新北市議會的「程序會」（正式會期開議前 的程序性會議）。查不到這類會議的獨立分類資料，不代表議會沒開過，是 現有 `會期類別` 分類（定期會／臨時會／成立大會）暫時沒有涵蓋到的部分。 ### 委員會（committee） - **不綁屆**，用生效日期／廢止日期記錄存續期間，是跨屆存在的常設編制， 不是每屆重新產生、也不會每屆換一批委員會。 - 目前**沒有**「委員會成員」資料——查不到「誰在哪個委員會」。 - 各議會委員會的設置方式差異很大：大議會（如臺北市）有多個固定業務 委員會；小議會（如連江縣）可能沒有分組委員會，直接全體審查。 ### 議案（bill） - 跟「會期」「場次」是不同顆粒度：會期／場次是「哪天上午/下午在幹嘛」， 議案是「當天大會/委員會實際在審的個別提案」本身（案號/提案人/案由/ 審查意見/議決）。 - **目前只涵蓋 4 個議會**（雲林縣、新北市、花蓮縣、臺南市），是持續擴充中 的實驗性補充資料，不是全國涵蓋的正式資料，跟「逐字稿」目前的定位相同。 - **`屆` 是從來源檔名解析出來的推測值，不是正式關聯欄位**，且**完全沒有 會期代碼／場次代碼**可以連結——來源的議事錄檔案常常一份就橫跨一個定期會 加好幾個臨時會，沒辦法精確對應到單一會期或場次，只能知道大概是哪一屆。 - `提案單位`／`提案人` 兩者通常只有一個有值：政府提案時只有 `提案單位` （議員提案時這欄常是空的），議員提案時只有 `提案人`。目前資料裡**沒有 獨立的「黨團提案」主體**，跟立法院「行政院／委員／黨團」三分不同。 - `連署人` 目前絕大多數是空的，不代表該議會沒有連署制度，只是目前解析 出來的樣本剛好沒觸發。 ### 會議（meet）／會議摘要（meet_note）／逐字稿（meet_transcript） - 「會議」對應到「場次」（sitting）底下實際發生的一場會議，不是對應 「會期」或「議員」；一個場次可能對應多筆會議（分組審查時），也可能 完全沒有（部分議會/部分場次尚未收錄）。 - 「會議」本身只有中繼資料（委員會或主旨／時間／地點），實際內容分兩種 顆粒度：「會議摘要」是簡短的速記／摘要式文字（一筆會議通常只有一筆 摘要）；「逐字稿」是逐句結構化的發言記錄（姓名／職稱／身分類別／ 發言內容），一筆會議可能有數百筆逐字稿記錄。兩者**不是互斥的**：同一場 會議可能同時有摘要跟逐字稿（分別來自原始文件的不同段落），也可能只有 其中一種、甚至兩種都沒有——查詢單一會議時請兩種都查，不要假設有其中 一種就沒有另一種。 - 目前只有部分議會、部分會議有逐字稿，且原因不只一種：有些是「這個議會 真的還沒收錄」，有些是「這個議會的逐字稿發布在其他管道，這個資料來源 本身就抓不到」。兩種情況目前在資料上呈現方式相同（查無逐字稿），**不要 把「查不到逐字稿」直接解讀成「這場會議沒有記錄」或「這個議會資料品質 差」**。 ## 識別碼設計原則 - 議會代碼是**自管 slug**（3 個英文字母，例：`tpe`），不是內政部行政區 代碼、也不是 ISO 3166-2 碼。採用自管代碼是因為內政部代碼在歷史上有 重複使用的問題（例如省轄高雄市與後來的直轄市高雄市，內政部代碼相同）， 無法唯一識別歷史上的不同機關。 - 會期代碼格式固定為 `{議會代碼}-{屆次}-{類別縮寫}{次別}`，類別縮寫 `r`=定期會、`e`=臨時會、`i`=成立大會（沒有次別）。這個縮寫規則橫跨 全部議會一致，可以直接從代碼反推類別，不需要另外查表。 ## 資料完整度會隨時間變動，不要依賴這份文件裡的任何具體涵蓋範圍描述 各型別、各議會目前實際的資料涵蓋範圍請即時查詢 `https://all.cc.govapi.tw/viewer/collection/completeness`（依議員／會期／ 場次／逐字稿四個維度，分成完整／部分缺漏／缺三種狀態，可切換是否顯示已 廢止議會），不要憑這份文件的描述或自己的推測判斷某個議會「應該」有沒有 資料。 ## 跟其他開放資料 API 的關係 - `ly.govapi.tw`：立法院（國會）open API，是本專案的姊妹專案（沿用同一套 框架），資料模型設計相似（型別、慣例命名接近），但資料內容完全不重疊， 兩者不能互查。