---
reviewed_by:
  rd: yo
  pm: Zoe
---
# 上市公司 — `tw.com.twse~ref~listed`

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

---

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

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

最簡查詢範例：curl -H "Authorization: Bearer YOUR_TOKEN" "https://data.openfun.tw/api/v1/datasets/tw.com.twse~ref~listed/records?per_page=20"

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

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

授權標注：使用此資料產出的內容需標注「資料來源：歐噴資料庫（data.openfun.tw）／台灣證券交易所」

**回應使用者時須附原始單筆查詢 URL** — 讓使用者可驗證 agent 回答內容：
將紀錄之 `股票代號` 值代入：`https://isin.twse.com.tw/isin/single_main.jsp?owncode={股票代號}`
例：紀錄 `股票代號=2330` → `https://isin.twse.com.tw/isin/single_main.jsp?owncode=2330`（台積電，台灣證券交易所 ISIN 系統官方頁，含市場別、產業別、上市日）

---

## 資料來源與更新頻率

| 項目 | 說明 |
|------|------|
| 原始來源 | 台灣證券交易所股份有限公司（TWSE） |
| 授權 | 政府資料開放授權條款 OGDL-Taiwan-1.0 |
| 更新頻率 | 不定期（公司資料變動時更新） |
| 涵蓋範圍 | 目前上市交易中的公司 |
| 筆數 | 見[資料集頁面](https://data.openfun.tw/datasets/tw.com.twse~ref~listed)（即時） |

---

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

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

- 「股票代號 1101 是哪家上市公司？它的地址是什麼？」
- 「台灣目前有多少家上市公司？各縣市分布如何？」
- 「產業別 01 的上市公司有哪些？」
- 「某上市公司的董事長、發言人、簽證會計師是誰？」
- 「某公司的統一編號是多少？」（可再對照稅籍資料）

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

- 「上櫃（TPEX）公司清單」（應查 `tw.com.tpex~ref~otc`）
- 「已下市公司的記錄」（應查 `tw.com.twse~ref~delisted`）
- 「公司的股價或財務數據」（本資料集無此資料）

---

## 欄位說明

| 欄位名稱（API 參數） | 型別 | 說明 |
|---------------------|------|------|
| `公司代號` | keyword（_id） | 股票代號 |
| `公司簡稱` | text（_name） | 公司簡稱 |
| `公司名稱` | text | 公司全名 |
| `英文簡稱` | text | 英文簡稱 |
| `營利事業統一編號` | keyword（ref: tw.gov.fia.eip~ref~business-tax） | 統編 |
| `外國企業註冊地國` | keyword（篩選器） | 外國企業註冊地國 |
| `產業別` | keyword（篩選器、ref: tw.com.twse~ref~industry） | 2 碼產業代碼 |
| `地址` | text | 公司登記地址 |
| `地址.縣市` | keyword（篩選器、ref: tw.openfun~entity~geo） | 5 碼行政區代碼 |
| `地址.鄉鎮市區` | keyword（篩選器、ref: tw.openfun~entity~geo） | 8 碼行政區代碼 |
| `英文通訊地址` | text | 英文通訊地址 |
| `董事長` | text | 董事長 |
| `總經理` | text | 總經理 |
| `發言人` | text | 發言人 |
| `發言人職稱` | keyword（篩選器） | 發言人職稱 |
| `代理發言人` | text | 代理發言人 |
| `總機電話` | text | 總機電話 |
| `傳真機號碼` | text | 傳真機號碼 |
| `電子郵件信箱` | text | 電子郵件信箱 |
| `網址` | text | 公司網址 |
| `成立日期` | date | 公司成立日（西元年） |
| `上市日期` | date | 上市/上櫃/興櫃日期（西元年） |
| `普通股每股面額` | text | 普通股每股面額 |
| `普通股每股面額.幣別` | keyword（篩選器） | 普通股每股面額-幣別 |
| `普通股每股面額.金額` | float | 普通股每股面額-金額 |
| `實收資本額` | number | 實收資本額 |
| `私募股數` | number | 私募股數 |
| `特別股` | number | 特別股數 |
| `已發行普通股數` | number | 已發行普通股數 |
| `編制財務報表類型` | keyword（篩選器） | 財報類型 |
| `股票過戶機構` | keyword（篩選器） | 股票過戶機構 |
| `過戶電話` | text | 過戶電話 |
| `過戶地址` | text | 過戶地址 |
| `簽證會計師事務所` | keyword（篩選器） | 簽證會計師事務所 |
| `簽證會計師1` | text | 簽證會計師 |
| `簽證會計師2` | text | 簽證會計師 |
| `出表日期` | date | 資料出表日期（西元年） |

欄位結構與 `tw.com.tpex~ref~otc` 相同，完整 37 欄由上方 schema 自動列出。各欄位語意與陷阱（`產業別` 非財政部行業分類、`地址.縣市/.鄉鎮市區` 為衍生代碼欄位）見 [knowledge.md](knowledge.md)。

---

## 典型查詢流程

### 流程 1：用股票代號查一家上市公司

```bash
curl -H "Authorization: Bearer YOUR_TOKEN" \
"https://data.openfun.tw/api/v1/datasets/tw.com.twse~ref~listed/records?公司代號=1101"
```

一次取得名稱、統編、地址、董事長、發言人、股本、簽證會計師等全部欄位。

### 流程 2：用公司名稱反查股票代號

```bash
curl -H "Authorization: Bearer YOUR_TOKEN" \
"https://data.openfun.tw/api/v1/datasets/tw.com.twse~ref~listed/records?q=台泥"
```

從結果取得 `公司代號`，需要完整資料時再用流程 1 查。

### 流程 3：判斷一檔股票現在在哪個市場（跨資料集）

同一股票代號依序查以下資料集，命中哪個就屬於該市場；全部查不到代表可能已終止：

```bash
curl -H "Authorization: Bearer YOUR_TOKEN" "https://data.openfun.tw/api/v1/datasets/tw.com.twse~ref~listed/records?公司代號=XXXX" # 上市？
curl -H "Authorization: Bearer YOUR_TOKEN" "https://data.openfun.tw/api/v1/datasets/tw.com.tpex~ref~otc/records?公司代號=XXXX" # 上櫃？
curl -H "Authorization: Bearer YOUR_TOKEN" "https://data.openfun.tw/api/v1/datasets/tw.com.tpex~ref~emerging/records?公司代號=XXXX" # 興櫃？
curl -H "Authorization: Bearer YOUR_TOKEN" "https://data.openfun.tw/api/v1/datasets/tw.com.twse~ref~delisted/records?上市編號=XXXX" # 終止上市？
curl -H "Authorization: Bearer YOUR_TOKEN" "https://data.openfun.tw/api/v1/datasets/tw.com.tpex~ref~delisted/records?股票代號=XXXX" # 終止上櫃？
```

> 現行三市場（上市/上櫃/興櫃）互斥，命中一個即屬該市場。終止名單為歷史記錄：曾轉換市場的公司會在多個終止名單出現（實測 `3454` 晶睿先終止上櫃再終止上市），且股票代號可能被不同公司重用，需以 `公司名稱`＋日期判讀。

### 流程 4：盤點某地區／產業的上市公司

```bash
# 台北市（63000）某產業（01）的上市公司清單
curl -H "Authorization: Bearer YOUR_TOKEN" \
"https://data.openfun.tw/api/v1/datasets/tw.com.twse~ref~listed/records?地址.縣市=63000&產業別=01&per_page=20"

# 各縣市上市公司數量（一次取得分布）
curl -H "Authorization: Bearer YOUR_TOKEN" \
"https://data.openfun.tw/api/v1/datasets/tw.com.twse~ref~listed/agg?group_by=地址.縣市"

# 各產業別上市公司數量
curl -H "Authorization: Bearer YOUR_TOKEN" \
"https://data.openfun.tw/api/v1/datasets/tw.com.twse~ref~listed/agg?group_by=產業別"
```

### 流程 5：用統一編號串接稅籍等其他資料

```bash
curl -H "Authorization: Bearer YOUR_TOKEN" \
"https://data.openfun.tw/api/v1/datasets/tw.gov.fia.eip~ref~business-tax/records?統一編號={流程 1 取得的統編}"
```

---

## 關聯資料集

| 資料集 | 說明 | 用途 |
|--------|------|------|
| [`tw.com.twse~ref~delisted`](../tw.com.twse~ref~delisted/skill.md) | 終止上市公司（TWSE） | 查詢某代號是否曾下市 |
| [`tw.com.tpex~ref~otc`](../tw.com.tpex~ref~otc/skill.md) | 上櫃公司（TPEX，現行） | 查詢上櫃（非上市）公司 |
| [`tw.com.tpex~ref~delisted`](../tw.com.tpex~ref~delisted/skill.md) | 終止上櫃公司（TPEX） | 查詢上櫃公司下櫃記錄 |
| [`tw.com.tpex~ref~emerging`](../tw.com.tpex~ref~emerging/skill.md) | 興櫃公司（TPEX） | 上市/上櫃前置階段 |
| [`tw.gov.fia.eip~ref~business-tax`](../tw.gov.fia.eip~ref~business-tax/skill.md) | 稅籍登記業者 | 以 `營利事業統一編號` 對照 |

---

## 注意事項與限制

1. 上市、上櫃、興櫃、終止上市、終止上櫃為 **5 個獨立資料集**，查不同市場要打不同 endpoint（見流程 3）。
2. 本資料集僅含「目前上市中」的公司；已下市者查 `tw.com.twse~ref~delisted`。
3. 查詢前先確認欄位語意陷阱（`產業別`≠財政部行業分類），詳見 [knowledge.md](knowledge.md)。

---

## 快速參考

| 項目 | 說明 |
|------|------|
| Records URL | `https://data.openfun.tw/api/v1/datasets/tw.com.twse~ref~listed/records` |
| Agg URL | `https://data.openfun.tw/api/v1/datasets/tw.com.twse~ref~listed/agg` |
| 認證 | `Authorization: Bearer {token}` 必填 |
| 取得 Token | 免費申請：https://data.openfun.tw/user |
| 全文搜尋 | `?q=關鍵字` |
| 精確篩選 | `?公司代號=1101`、`?產業別=01`、`?地址.縣市=63000` |
| 分頁 | `?page=1&per_page=20` |