---
reviewed_by:
  rd: yo
  pm:
---
# `tw.gov.cec~txn~party-votes` — 中選會不分區政黨得票數

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

---

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

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

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

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

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

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

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

---

## 資料來源與更新頻率

| 項目 | 說明 |
|------|------|
| 原始來源 | 中央選舉委員會選舉資料庫（db.cec.gov.tw） |
| 更新頻率 | 不定期（每有新一屆立委選舉後新增） |
| 涵蓋範圍 | 第 7–11 屆立委不分區政黨票（2008–2024 年） |
| 總筆數 | 約 62 萬筆（2026 年） |

---

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

**可以回答：**
- 「某政黨在某屆立委的全國政黨票得票？」（取 `行政區層級=national`）
- 「某政黨政黨票在各縣市／鄉鎮／村里的分布？」（取對應 `行政區層級`）

**無法回答：**
- 「政黨提名人數、號次、當選席次」（請查 [`tw.gov.cec~ref~party`](../tw.gov.cec~ref~party/skill.md)）
- 「不分區票的選舉人數、投票率、廢票」（請查 [`tw.gov.cec~txn~votes-geo`](../tw.gov.cec~txn~votes-geo/skill.md)，選區代碼=`不分區`）
- 「區域候選人得票」（請查 [`tw.gov.cec~txn~candidates-votes`](../tw.gov.cec~txn~candidates-votes/skill.md)）

---

## 欄位說明

| 欄位名稱（API 參數） | 型別 | 說明 |
|---------------------|------|------|
| `識別碼` | keyword（_id） | {選舉代碼}:{政黨代碼}:{投開票所識別碼|行政區代碼} |
| `不分區政黨識別碼` | keyword（篩選器、ref: tw.gov.cec~ref~party） | {選舉代碼}:{政黨代碼} |
| `行政區層級` | keyword（篩選器） | 行政區層級 |
| `行政區代碼` | keyword（篩選器、ref: tw.openfun~entity~geo） | 行政區代碼 |
| `投開票所識別碼` | keyword（篩選器、ref: tw.gov.cec~ref~polling-station） | 投開票所識別碼 |
| `得票數` | integer | 得票數 |

### 關鍵欄位補充說明

| 欄位 | 型別 | 重要說明 |
|------|------|---------|
| `識別碼` | keyword（_id） | 格式 `{選舉代碼}:{政黨代碼}:{第三段}`；第三段於 `village` 層為 `投開票所識別碼`、其餘層為 `行政區代碼`；national 層行政區代碼為空，結尾為 `:` |
| `不分區政黨識別碼` | keyword（篩選器、ref: tw.gov.cec~ref~party） | 對應 ref~party 的 `識別碼`，格式 `{選舉代碼}:{政黨代碼}`（如 `ELC-L0-11:16`）。⚠️ 本表選舉資訊只在此欄，無獨立 `選舉代碼` 欄位 |
| `行政區層級` | keyword（篩選器） | `village` / `town` / `county` / `national`，四層獨立，不可相加 |
| `行政區代碼` | keyword（篩選器、ref: tw.openfun~entity~geo） | 鄉鎮 8 碼、縣市 5 碼；national 層為空字串。**`village` 層有 `投開票所識別碼` 時此欄留空**（地理歸屬改用 `投開票所識別碼`）；無票所資訊時才 fallback 填村里 `{8碼}-{3碼}` |
| `投開票所識別碼` | keyword（篩選器、ref: [tw.gov.cec~ref~polling-station](../tw.gov.cec~ref~polling-station/skill.md)） | **僅 `village` 層有值**。對應 polling-station `識別碼`；村里層每列即一個投開票所，串 polling-station 取涵蓋村里（可多村里） |
| `得票數` | integer | 該行政區（或彙總層）政黨票得票數；村里層為該投開票所整體得票（不拆分到各村里） |

---

## ⚠️ 兩個關鍵注意點

1. **沒有 `選舉代碼` 欄位**：要篩特定屆某政黨，用完整 `不分區政黨識別碼`（如 `ELC-L0-11:16` = 第11屆民進黨）。
2. **層級不可相加**：village/town/county/national 是同票不同粒度。全國總票取 `national`，地理分布取單一層級。

---

## API 呼叫範例

**Records URL：** `https://data.openfun.tw/api/v1/datasets/tw.gov.cec~txn~party-votes/records`
**Agg URL：** `https://data.openfun.tw/api/v1/datasets/tw.gov.cec~txn~party-votes/agg`

> 以下為各自獨立的查法，彼此無先後關係。

### 查某政黨某屆全國得票

```bash
curl -H "Authorization: Bearer YOUR_TOKEN" \
  "https://data.openfun.tw/api/v1/datasets/tw.gov.cec~txn~party-votes/records?不分區政黨識別碼=ELC-L0-11:16&行政區層級=national"
```

### 查某屆所有政黨的全國得票（排名比較）

```bash
curl -H "Authorization: Bearer YOUR_TOKEN" \
  "https://data.openfun.tw/api/v1/datasets/tw.gov.cec~txn~party-votes/records?行政區層級=national&per_page=100"
```

### 查某政黨某屆各縣市得票

```bash
curl -H "Authorization: Bearer YOUR_TOKEN" \
  "https://data.openfun.tw/api/v1/datasets/tw.gov.cec~txn~party-votes/records?不分區政黨識別碼=ELC-L0-11:16&行政區層級=county&per_page=100"
```

### 查某縣市某屆所有政黨得票

```bash
# 臺北市（63000）第 11 屆各政黨得票
curl -H "Authorization: Bearer YOUR_TOKEN" \
  "https://data.openfun.tw/api/v1/datasets/tw.gov.cec~txn~party-votes/records?行政區代碼=63000&行政區層級=county&per_page=100"
```

### 取得政黨名稱與當選席次（JOIN）

```bash
# 以 不分區政黨識別碼 串 `tw.gov.cec~ref~party` 取政黨名稱、提名人數、當選席次
curl -H "Authorization: Bearer YOUR_TOKEN" \
  "https://data.openfun.tw/api/v1/datasets/tw.gov.cec~ref~party/records?識別碼={不分區政黨識別碼}"
```

### 用 agg 查各行政區層級筆數分布

```bash
curl -H "Authorization: Bearer YOUR_TOKEN" \
  "https://data.openfun.tw/api/v1/datasets/tw.gov.cec~txn~party-votes/agg?group_by=行政區層級"
```

回應格式：
```json
{
  "total_records": 617818,
  "groups": [
    { "key": "village", "stats": { "count": 588066 } },
    { "key": "town",    "stats": { "count": 27968 } },
    { "key": "county",  "stats": { "count": 1708 } },
    { "key": "national","stats": { "count": 76 } }
  ]
}
```

---

## 注意事項與限制

1. **務必加篩選**：逾 60 萬筆，至少帶 `不分區政黨識別碼` 或 `行政區代碼`+`行政區層級`。
2. **沒有 `選舉代碼` 欄位**：選舉藏在 `不分區政黨識別碼`。
3. **層級不可相加**：總計取 `national`。
4. **只有得票數**：提名人數／當選席次在 [`tw.gov.cec~ref~party`](../tw.gov.cec~ref~party/skill.md)；選舉人數／廢票在 [`tw.gov.cec~txn~votes-geo`](../tw.gov.cec~txn~votes-geo/skill.md)（選區代碼=`不分區`）。
5. **僅立委不分區**：政黨票只有立委選舉有。

---

## 關聯資料集

| 資料集 | 說明 | 用途 |
|--------|------|------|
| [`tw.gov.cec~ref~party`](../tw.gov.cec~ref~party/skill.md) | 政黨參選資料 | `不分區政黨識別碼` 引用其 `識別碼` |
| [`tw.gov.cec~ref~election-event`](../tw.gov.cec~ref~election-event/skill.md) | 投票事件 | 選舉代碼內嵌於 `不分區政黨識別碼`，拆出後對應其 `vote_id` |
| [`tw.openfun~entity~geo`](../tw.openfun~entity~geo/skill.md) | 行政區代碼 | `行政區代碼` 引用 |
| [`tw.gov.cec~txn~votes-geo`](../tw.gov.cec~txn~votes-geo/skill.md) | 投票概況 | 不分區票選舉人數／廢票（選區代碼=`不分區`） |
| [`tw.gov.cec~txn~candidates-votes`](../tw.gov.cec~txn~candidates-votes/skill.md) | 候選人得票 | 第一票（區域／原住民候選人） |

---

## 快速參考

| 項目 | 說明 |
|------|------|
| Records URL | `https://data.openfun.tw/api/v1/datasets/tw.gov.cec~txn~party-votes/records` |
| Agg URL | `https://data.openfun.tw/api/v1/datasets/tw.gov.cec~txn~party-votes/agg` |
| 認證 | `Authorization: Bearer {token}` 必填 |
| 取得 Token | https://data.openfun.tw/user |
| 總筆數 | 約 62 萬筆（第 7–11 屆，2026 年） |
| 主鍵 | `識別碼`（`{選舉代碼}:{政黨代碼}:{行政區代碼}`） |
| 篩選器欄位 | `不分區政黨識別碼`、`行政區層級`、`行政區代碼` |
| 層級 | `village` / `town` / `county` / `national`（不可相加，總計取 national） |
| 注意 | 無 `選舉代碼` 欄位，選舉藏在 `不分區政黨識別碼` |
| 更新頻率 | 不定期，每有新一屆立委選舉時新增一批 |
| 來源 | 中央選舉委員會（db.cec.gov.tw） |
| 分頁 | `?page=1&per_page=20` |
| Records 回應格式 | JSON，含 `total`、`page`、`per_page`、`records[]` |
| Agg 回應格式 | JSON，含 `total_records`、`total_groups`、`groups[].key`、`groups[].stats.count` |