---
reviewed_by:
  rd: yo
  pm: Zoe
---
# `tw.gov.cec~txn~votes-geo` — 中選會各選區投票概況

> **給 AI 閱讀的資料集說明。**
> 人類可在 https://data.openfun.tw/datasets/tw.gov.cec~txn~votes-geo 看到同份內容的網頁版。
> 詳細資料知識見 [knowledge.md](knowledge.md)。

---

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

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

最簡查詢範例：`curl -H "Authorization: Bearer YOUR_TOKEN" "https://data.openfun.tw/api/v1/datasets/tw.gov.cec~txn~votes-geo/records?選舉代碼=ELC-L0-11&選區代碼=不分區&行政區層級=national"`

**Token 是必要條件，沒有 Token 就無法查資料。**
如果使用者沒有 Token，請先請使用者前往 https://data.openfun.tw/user 申請。

⚠️ **資料量大（逾 47 萬筆）**：務必加篩選條件（`選舉代碼`、`選區代碼`、`行政區層級`、`行政區代碼`），切勿無條件全表掃描。

禁止抓取 HTML 頁面（本平台有 bot 保護）。

授權標注：使用此資料產出的內容需標注「資料來源：歐噴資料庫（data.openfun.tw）／中央選舉委員會」

---

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

**可以回答：**
- 「某次選舉某行政區的選舉人數、投票數、投票率、廢票率？」
- 「某次選舉全國投票率？」（取 `選區代碼=00`、行政區代碼空、national）
- 「不分區政黨票的選舉人數與廢票？」（選區代碼=`不分區`）

**無法回答：**
- 「候選人得票數」（請查 [`tw.gov.cec~txn~candidates-votes`](../tw.gov.cec~txn~candidates-votes/skill.md)）
- 「政黨各黨得票數」（請查 [`tw.gov.cec~txn~party-votes`](../tw.gov.cec~txn~party-votes/skill.md)）

---

## ⭐ 核心概念：`選區代碼` 區分選票別

同一場立委選舉同時有區域／平地原住民／山地原住民／不分區多張選票，各自獨立計票、選舉人數不同。本表用 `選區代碼` 區分：

| `選區代碼` | 選票別 |
|-----------|--------|
| `00` | 區域（彙總）；總統、縣市長、村里長等單一選票選舉多為 `00` |
| `01`、`02`… | 區域各選區 |
| `平地原住民` | 平地原住民票 |
| `山地原住民` | 山地原住民票 |
| `不分區` | 不分區政黨票 |

**算投票率前一定要先選對 `選區代碼`**，否則會把不同選票的選舉人數混在一起。

---

## 欄位說明

| 欄位名稱 | 型別 | 說明 |
|---------|------|------|
| `識別碼` | keyword（_id） | 格式 `{選舉代碼}:{選區代碼}:{第三段}`；第三段於 `village` 層為 `投開票所識別碼`、其餘層為 `行政區代碼`；national 層行政區代碼空，結尾為 `:` |
| `選舉代碼` | keyword（篩選器、ref: [tw.gov.cec~ref~election-event](../tw.gov.cec~ref~election-event/skill.md)） | 對應 election-event 的 `vote_id` |
| `選區代碼` | keyword（篩選器） | 數字（`00` 彙總、`01+` 選區）或 `平地原住民`／`山地原住民`／`不分區` |
| `行政區層級` | keyword（篩選器） | `village` / `town` / `county` / `national` |
| `行政區代碼` | keyword（篩選器、ref: tw.openfun~entity~geo） | 5/8/12 碼；全國為空。**`village` 層有 `投開票所識別碼` 時此欄留空**（地理歸屬改用 `投開票所識別碼`）；無票所資訊時才 fallback 填村里代碼 |
| `投開票所識別碼` | keyword（篩選器、ref: [tw.gov.cec~ref~polling-station](../tw.gov.cec~ref~polling-station/skill.md)） | **僅 `village` 層有值**。對應 polling-station `識別碼`；村里層每列即一個投開票所，串 polling-station 取涵蓋村里（可多村里） |
| `選舉人數` | integer | 有投票權的人數 |
| `投票數` | integer | 有效票數 + 廢票數（投票率 = 投票數 ÷ 選舉人數） |
| `有效票數` | integer | 有效票數 |
| `廢票數` | integer | 廢票數（廢票率 = 廢票數 ÷ 投票數）。村里層各數值為該投開票所整體（不拆分到各村里） |

---

## 查全國總計（重要）

篩 `行政區層級=national`、`行政區代碼` 為空，每種選票剛好一筆：
- **區域票全國**：`選區代碼` 為數字那筆。多選區選舉（區域立委、議員、代表）是 `00`；單一選區選舉（總統、縣市長、村里長、立委補選）是它唯一的數字代碼（如總統為 `01`）。
- **原住民／不分區票全國**：對應的 `選區代碼`（`平地原住民`／`山地原住民`／`不分區`）。

---

## API 呼叫範例

### 範例 1：查某次選舉全國不分區票投票概況

```bash
curl -H "Authorization: Bearer YOUR_TOKEN" \
"https://data.openfun.tw/api/v1/datasets/tw.gov.cec~txn~votes-geo/records?選舉代碼=ELC-L0-11&選區代碼=不分區&行政區層級=national"
# → 選舉人數 19,566,007、投票數 14,044,052、有效票 13,776,736、廢票 267,316
```

### 範例 2：查某縣市某次選舉區域票投票概況

```bash
# 台北市（63000）第10屆立委 區域票彙總
curl -H "Authorization: Bearer YOUR_TOKEN" \
"https://data.openfun.tw/api/v1/datasets/tw.gov.cec~txn~votes-geo/records?選舉代碼=ELC-L0-10&選區代碼=00&行政區代碼=63000&行政區層級=county"
```

### 範例 3：查某次選舉各鄉鎮投票率

```bash
curl -H "Authorization: Bearer YOUR_TOKEN" \
"https://data.openfun.tw/api/v1/datasets/tw.gov.cec~txn~votes-geo/records?選舉代碼=ELC-L0-11&選區代碼=不分區&行政區層級=town&per_page=400"
```

---

## 注意事項與限制

1. **務必加篩選**：逾 47 萬筆，至少帶 `選舉代碼`+`選區代碼`+`行政區層級`。
2. **先選對 `選區代碼`**：區域／原住民／不分區選舉人數不同，混用會算錯投票率。
3. **全國區域票＝唯一的數字選區代碼列**：篩 national、行政區代碼空，區域票即 `選區代碼` 為數字那筆（多選區為 `00`，總統等單一選區為其唯一代碼）。
4. **層級不可相加**：village/town/county/national 是同統計不同粒度。
5. **只有投票概況**：得票數在 [`tw.gov.cec~txn~candidates-votes`](../tw.gov.cec~txn~candidates-votes/skill.md) 與 [`tw.gov.cec~txn~party-votes`](../tw.gov.cec~txn~party-votes/skill.md)。
6. **少數歷史村里缺村里層**：部分歷年改名／裁併／罕用字的村里地名對不上現行行政區代碼，村里層會缺漏，彙總層不受影響；立委補選的部分村里亦可能缺漏。
7. **不含公投／修憲**。
8. **村里層即投開票所層**：村里層每列是一個投開票所（`行政區代碼` 空、鍵為 `投開票所識別碼`），跨村里共用的投開票所只有一列整體投票概況、不拆分到各村里，故取不到「合併所」內各村里個別概況；要對應村里以 `投開票所識別碼` 串 [`tw.gov.cec~ref~polling-station`](../tw.gov.cec~ref~polling-station/skill.md)（其 `村里代碼` 可多村里）。各列互斥，**村里層加總不需去重**。

---

## 關聯資料集

| 資料集 | 說明 | 用途 |
|--------|------|------|
| [`tw.gov.cec~ref~election-event`](../tw.gov.cec~ref~election-event/skill.md) | 投票事件 | `選舉代碼` 引用 |
| [`tw.openfun~entity~geo`](../tw.openfun~entity~geo/skill.md) | 行政區代碼 | `行政區代碼` 引用 |
| [`tw.gov.cec~txn~candidates-votes`](../tw.gov.cec~txn~candidates-votes/skill.md) | 候選人得票 | 同行政區的得票數 |
| [`tw.gov.cec~txn~party-votes`](../tw.gov.cec~txn~party-votes/skill.md) | 不分區政黨得票 | 對應 `選區代碼=不分區` |

---

## 快速參考

| 項目 | 說明 |
|------|------|
| Records URL | `https://data.openfun.tw/api/v1/datasets/tw.gov.cec~txn~votes-geo/records` |
| 認證 | `Authorization: Bearer {token}` 必填 |
| 總筆數 | 見 Portal 資料集頁面（隨新選舉增加） |
| 主鍵 | `識別碼`（`{選舉代碼}:{選區代碼}:{行政區代碼}`） |
| 篩選器欄位 | `選舉代碼`、`選區代碼`、`行政區層級`、`行政區代碼` |
| 選區代碼 | `00` 彙總／`01+` 選區／`平地原住民`／`山地原住民`／`不分區`（數字選區值數量隨選舉增加，以 agg 查） |
| 層級 | `village` / `town` / `county` / `national`（不可相加） |
| 更新頻率 | 不定期，每有新選舉資料釋出時新增 |
| 來源 | 中選會選舉資料庫（db.cec.gov.tw） |
| 用途 | 各選區投票概況（選舉人數、投票數、有效票、廢票）；算投票率／廢票率 |