FinceptTerminal 台灣股市資料連接器實戰指南：以 TWSE/TPEX 行情、指數與公司資訊擴充開源終端

FinceptTerminal 台灣股市資料連接器實戰指南：以 TWSE/TPEX 行情、指數與公司資訊擴充開源終端

【免费下载链接】FinceptTerminalFinceptTerminal is a modern finance application offering advanced market analytics, investment research, and economic data tools, designed for interactive exploration and>项目地址: https://gitcode.com/GitHub_Trending/fi/FinceptTerminal

本指南圍繞 FinceptTerminal 開源社群分支新增的taiwan_market_connector.py展開，完整講解如何在不重新編譯 C++ 程式碼的前提下，為 FinceptTerminal 加入台灣上市（TWSE）與上櫃（TPEX）股票的歷史 OHLCV、公司基本面、大盤指數、市場概況與強勢股排行等能力。讀完本文，你將掌握連接器的安裝部署、三步啟用流程、全部公開 API 的呼叫方式與參數細節，並理解其底層資料來源與限速策略，可直接在自己的 FinceptTerminal 環境中查詢台股資料。

這個分支做了什麼：為 FinceptTerminal 補上台股資料能力

FinceptTerminal 是一套跨平台的現代化金融桌面終端（Qt 6 + C++20 前端、Python 資料層），其內建的股市資料連接器預設以美股（NYSE / NASDAQ）為主要市場。本開源社群貢獻分支在fincept-qt/src/python/目錄下新增了單一 Python 檔案：

fincept-qt/src/python/taiwan_market_connector.py

這個連接器讓你在 FinceptTerminal 中直接查詢：

重要：本修改僅涉及 Python 層，不需要重新編譯 C++ 程式碼。連接器檔案可以直接執行、獨立自測，也可作為模組被其他 Python 程式引用。

從倉庫源碼看，連接器同時提供了完整的「連接器元資料」（CONNECTOR_META，見 taiwan_market_connector.py），包含連接器 idtaiwan_twse、名稱、區域、幣別以及七個可呼叫函式的映射，這正是 FinceptTerminal 連接器登錄（connector registry）消費的標準結構——也就是說，這個檔案既是獨立工具，也設計成可以被終端內部的資料來源框架掛載。

與 C++ 層的配合：台股後綴的雙重保障

FinceptTerminal 的 C++ 命令列（Command Bar）資產搜尋功能本身已內建了全球交易所代碼後綴映射表，位於 CommandBar_Assets.cpp，其中就包含{"TPEX", ".TWO"}這條規則——也就是說終端原有的資產搜尋就能把上櫃交易所識別碼轉成 Yahoo Finance 的.TWO後綴。而本連接器在 Python 層以TWSE_SUFFIX = ".TW"與TPEX_SUFFIX = ".TWO"重新實現了同一套規則（taiwan_market_connector.py），並透過_yahoo_symbol()輔助函式統一轉換。兩層規則相互印證，確保「上市用.TW、上櫃用.TWO」的慣例在整個終端內一致。

授權說明（重要，請先閱讀）

原始專案授權

FinceptTerminal 採用雙授權制：

• AGPL-3.0：適用於個人、學術與開源用途（免費）
• Fincept 商業授權：任何商業用途皆需取得此授權

本分支的授權立場

本分支依照AGPL-3.0條款釋出，這表示：

✅你可以：

• 免費下載、使用、修改本程式碼
• 將本修改再分享給其他人（須保持相同授權）
• 用於個人學習、學術研究、非商業專案

❌你不可以：

• 將本程式碼或衍生作品用於任何商業目的（需另行取得 Fincept 商業授權）
• 移除原始版權聲明
• 以「Fincept」、「Fincept Terminal」等商標命名你的衍生產品

合規作法

1. 分支的LICENSE檔案完整保留 AGPL-3.0 全文
2. 每個修改的檔案頭部都有明確的原始來源聲明（連接器檔案開頭的 docstring 即標註了License : AGPL-3.0 (same as upstream FinceptTerminal)與 Upstream 來源）
3. README 頂部清楚標示這是社群貢獻分支，非官方版本
4. 若你有商業需求，請聯絡 Fincept Corporation

安裝方式

前置需求

本分支與原版相同，需要（與 CMakeLists.txt 中實際強制的工具鏈版本一致）：

• Python 3.11.9（由 CMake 自動管理，透過PythonSetupManager與 UV 管理的 venv 環境）
• Qt 6.8.3（CMake 固定FINCEPT_QT_VERSION 6.8.3，支援 EXACT / MINOR / ANY 三種鎖定模式）
• CMake 3.27+（cmake_minimum_required(VERSION 3.27)）
• C++20 編譯器（MSVC 2022 19.40+ / GCC 12.3+ / Apple Clang 15+，CMake 在 configure 階段即檢查並以 FATAL_ERROR 拒絕過舊工具鏈）

方法一：直接使用預編譯版本（推薦新手）

本分支的 Python 連接器不需要重新編譯C++ 程式碼。你可以先下載官方預編譯版本安裝後，再手動加入本連接器檔案：

# 1. 下載並安裝官方預編譯版本（Windows / macOS / Linux） # 2. 複製台灣股市連接器到 Python 層目錄 cp taiwan_market_connector.py 路徑/到/fincept-qt/src/python/

方法二：從原始碼建置（開發者）

# Clone 本分支 git clone https://github.com/你的帳號/FinceptTerminal.git cd FinceptTerminal # Linux / macOS — 一鍵建置 chmod +x setup.sh && ./setup.sh # Windows（在 VS 2022 Developer Command Prompt 執行） setup.bat

安裝 Python 相依套件

連接器使用以下套件，通常 FinceptTerminal 環境已內建：

pip install yfinance requests pandas

若要使用twstock進行更完整的即時分析：

pip install twstock

從源碼看，連接器的CONNECTOR_META中聲明的依賴為["yfinance", "requests", "pandas"]（taiwan_market_connector.py），與上述清單一致；twstock屬於選用依賴，僅用於即時報價與技術分析輔助。

啟用台灣股市連接器

步驟 1：複製連接器檔案

將taiwan_market_connector.py放入：

FinceptTerminal/ └── fincept-qt/ └── src/ └── python/ └── taiwan_market_connector.py ← 放在這裡

步驟 2：在連接器登錄中註冊

找到fincept-qt/src/python/目錄中的連接器登錄檔案（通常是data_sources.py或connectors/__init__.py），加入以下程式碼：

from .taiwan_market_connector import CONNECTOR_META as TW_META # 在現有連接器字典中加入 AVAILABLE_CONNECTORS["taiwan_twse"] = TW_META

需要說明的是，連接器檔案本身已定義好CONNECTOR_META字典（id 為taiwan_twse），註冊時直接引用即可，無需自行重寫元資料。

步驟 3：在應用程式介面中啟用

啟動 FinceptTerminal 後：

1. 前往Data Sources（資料來源）設定頁面
2. 找到Taiwan Stock Exchange (TWSE / TPEX)
3. 點擊啟用
4. 回到主畫面即可使用台灣股市功能

功能說明與程式碼範例

以下範例可在 Python 直譯器中直接執行，用於驗證連接器是否正常運作。所有範例函式都定義於 taiwan_market_connector.py，並帶有完整 docstring 參數說明。

查詢個股歷史價格

核心函式get_tw_stock_history(symbol, start, end, market, interval)：

from taiwan_market_connector import get_tw_stock_history # 查詢台積電（上市股票，加 .TW 後綴） df = get_tw_stock_history("2330", start="2024-01-01", market="TWSE") print(df.tail(10)) # 查詢上櫃股票（加 .TWO 後綴） df_otc = get_tw_stock_history("6669", start="2024-01-01", market="TPEX") print(df_otc.tail(5)) # 查詢週K資料 df_weekly = get_tw_stock_history("2330", start="2023-01-01", interval="1wk") print(df_weekly)

輸出範例（DataFrame，欄位為 Open/High/Low/Close/Volume，索引為 Date）：

Open High Low Close Volume Date 2025-04-28 780.0 790.0 778.0 788.0 28500000 2025-04-29 789.0 795.0 785.0 792.0 31200000 ...

從源碼看，該函式內部會先將裸代碼轉為 Yahoo Finance 格式（2330→2330.TW），呼叫yf.download()後會做兩件事：把索引命名為Date、並展平 yfinance 0.2.x 起可能出現的 MultiIndex 欄位（df.columns.get_level_values(0)），最後只保留["Open", "High", "Low", "Close", "Volume"]五個欄位。若回傳空資料會直接拋出ValueError，錯誤訊息提示檢查代碼與市場類型（TWSE vs TPEX）。

查詢公司基本資訊

from taiwan_market_connector import get_tw_stock_info info = get_tw_stock_info("2330") for key, value in info.items(): print(f"{key:<15}: {value}")

輸出範例：

name : Taiwan Semiconductor Manufacturing Company Limited symbol : 2330 exchange : TWSE sector : Technology market_cap : 15280000000000 currency : TWD pe_ratio : 22.4 pb_ratio : 5.8 div_yield : 0.018 52w_high : 1080.0 52w_low : 688.0 current_price : 788.0

從源碼看，get_tw_stock_info回傳的字典比上面輸出更完整，還包含yf_symbol（Yahoo 格式代碼）、industry（產業細分）、website（公司官網）等欄位，並對current_price做了currentPrice與regularMarketPrice的雙重取值備援。

查詢大盤指數

from taiwan_market_connector import get_tw_index # 台灣加權指數（TAIEX） taiex = get_tw_index("^TWII", period="3mo") print(taiex.tail(5)) # 上櫃指數 tpex_idx = get_tw_index("^TWOII", period="1mo") print(tpex_idx.tail(5))

常用指數代碼：

查詢市場概況

from taiwan_market_connector import get_tw_market_overview overview = get_tw_market_overview() print(f"日期：{overview['date']}") print(f"成交量：{overview['trade_volume']}") print(f"成交值：{overview['trade_value']}") print(f"加權指數收盤：{overview['taiex_close']}") print(f"漲跌：{overview['taiex_change']}")

從源碼看，此函式請求 TWSE OpenAPI 的/exchangeReport/FMTQIK端點，取回傳清單的最後一筆（data[-1]）作為最新交易日，解析出Date、TradeVolume、TradeValue、Transaction、ClosePrice、Change六個欄位並重新命名為英文鍵。非交易時段請求可能回傳空清單，此時函式回傳空字典{}，呼叫端需自行處理。

查詢當日強勢股

from taiwan_market_connector import get_tw_top_movers # 取得漲幅前 10 名 movers = get_tw_top_movers(top_n=10) print(movers)

從源碼看，get_tw_top_movers(top_n)請求 TWSE OpenAPI 的/exchangeReport/MI_INDEX20即時資料端點，將欄位重新命名為英文（Code→symbol、Name→name、TradeVolume→volume、ClosePrice→close、Change→change、ChangeRange→change_pct），並將漲跌幅轉為數值後降冪排序，最後取前top_n筆。注意 TWSE OpenAPI 的即時資料在盤中約每 5 分鐘更新一次。

搜尋股票

from taiwan_market_connector import search_tw_stocks # 依中文名稱搜尋 results = search_tw_stocks("金融") for r in results: print(f"{r['code']} {r['name']:6} {r['english']}") # 依產業搜尋 results = search_tw_stocks("Semiconductors") for r in results: print(r)

從源碼看，search_tw_stocks(query)對內建參考表MAJOR_TW_STOCKS進行不區分大小寫的模糊比對，比對欄位涵蓋股票代碼、中文名稱、英文名稱與產業（sector）四種；空查詢則回傳整份參考表的複本。

執行完整自我測試

連接器檔案設計為可直接執行，執行__main__區塊會依序跑四項自測：

# 在專案根目錄執行 python fincept-qt/src/python/taiwan_market_connector.py

若所有功能正常，將看到：

=== Taiwan Market Connector — Self Test === 1. TSMC (2330) last 5 trading days: ... 2. TSMC company info: ... 3. TAIEX index (last 5 days): ... 4. Search 'semi': ... ✓ All tests passed.

從源碼看，自測流程依序為：抓取台積電 2025 年以來的歷史價格尾 5 筆、輸出台積電公司資訊、抓取 TAIEX 近一個月指數尾 5 筆、以"semi"關鍵字搜尋參考表。這個設計讓使用者不必先整合進終端，就能驗證網路與依賴套件是否就緒。

支援的股票代碼

上市股票（TWSE 台灣證券交易所）

使用格式：代碼.TW（在 Yahoo Finance 中）

補充說明：從源碼的MAJOR_TW_STOCKS參考表（taiwan_market_connector.py）看，內建清單還收錄了「力積電（6770, PSMC, Semiconductors）」，該筆未列於 README 表格中，但同樣可透過search_tw_stocks搜尋到；清單依產業分類註記為 Semiconductors / Electronics / Financials / Telecom / Materials 五大類。

上櫃股票（TPEX 證券櫃檯買賣中心）

使用格式：代碼.TWO（在 Yahoo Finance 中）

上櫃股票請傳入market="TPEX"參數。常見上櫃股：

取得完整上市股票清單

除了上述參考表，連接器還提供動態抓取 TWSE 官方完整清單的能力：

from taiwan_market_connector import get_tw_all_listed_stocks all_stocks = get_tw_all_listed_stocks() print(f"共 {len(all_stocks)} 檔上市股票") print(all_stocks.head(10))

從源碼看，該函式請求 TWSE OpenAPI 的/company/BWIBBU_d端點，直接以pd.DataFrame回傳原始欄位（含code、name、isin、listing_date、market_type等），可用於擴充內建參考表或做全市場掃描。

資料來源說明

注意事項：

• TWSE OpenAPI 有請求速率限制（每 5 秒 3 次），本連接器已內建等待邏輯。
• Yahoo Finance 的資料可能有 15–20 分鐘延遲（非 Premium 用戶）。
• 盤中即時資料建議透過 TWSE OpenAPI 取得。

源碼層的限速實作

從源碼看，連接器對 TWSE OpenAPI 的限速處理是透過模組級全域變數實現的（taiwan_market_connector.py）：

_LAST_TWSE_CALL: float = 0.0 _TWSE_MIN_INTERVAL = 1.8 # seconds between calls to be safe

_twse_get()輔助函式在每次請求前計算距離上次呼叫的間隔，若不足 1.8 秒則time.sleep()補足，並以 10 秒 timeout 保護請求、resp.raise_for_status()確保非 2xx 回應直接拋出例外。也就是說，即使文件載明的官方上限是「每 5 秒 3 次」，連接器實際採用了更保守的約 1.8 秒/次節奏，確保合規並降低被限流的風險。所有 TWSE OpenAPI 相關函式（市場概況、強勢股、完整清單）都共用這條限速路徑。

常見問題 FAQ

Q1：執行時出現No data returned for 2330.TW，怎麼辦？

可能原因：

• 股票代碼或市場類型（TWSE/TPEX）錯誤
• 查詢日期範圍包含假日或超出資料範圍
• Yahoo Finance 暫時性網路問題

解決方式：

# 確認代碼正確（上市用 .TW，上櫃用 .TWO） import yfinance as yf ticker = yf.Ticker("2330.TW") print(ticker.history(period="5d")) # 直接測試

Q2：TWSE OpenAPI 回傳空值？

TWSE OpenAPI 僅在台灣股市交易時間（週一至週五 09:00–13:30 台灣時間）有即時資料。非交易時段請求會回傳最新收盤資料或空陣列。

Q3：為什麼不直接支援 Polygon 或 Bloomberg 的台股資料？

Polygon 的台股資料需要付費方案。TWSE OpenAPI + Yahoo Finance 的組合對於個人研究與學習已足夠，且完全免費。

Q4：可以查詢 ETF 嗎？

可以！台灣 ETF 使用相同格式：

# 元大台灣50（0050） df = get_tw_stock_history("0050", market="TWSE") # 元大高股息（0056） df = get_tw_stock_history("0056", market="TWSE")

Q5：如何取得完整的上市股票清單？

from taiwan_market_connector import get_tw_all_listed_stocks all_stocks = get_tw_all_listed_stocks() print(f"共 {len(all_stocks)} 檔上市股票") print(all_stocks.head(10))

連接器元資料與整合點

若要在自己的程式或終端內部框架中掛載此連接器，可直接引用檔案底部的CONNECTOR_META（taiwan_market_connector.py）：

CONNECTOR_META = { "id": "taiwan_twse", "name": "Taiwan Stock Exchange (TWSE / TPEX)", "region": "TW", "currency": "TWD", "description": "...", "functions": { "history": get_tw_stock_history, "info": get_tw_stock_info, "index": get_tw_index, "market_overview": get_tw_market_overview, "top_movers": get_tw_top_movers, "search": search_tw_stocks, "all_listed": get_tw_all_listed_stocks, }, "dependencies": ["yfinance", "requests", "pandas"], }

由此可見連接器暴露了七個統一入口，覆蓋「歷史行情、公司資訊、指數、市場概況、強勢股、搜尋、全清單」七種查詢語意，任何消費方能以一致的字典結構完成註冊與呼叫。

如何貢獻

歡迎任何形式的貢獻！

貢獻流程

# 1. Fork 本 Repository（點擊 GitHub 右上角 Fork 按鈕） # 2. Clone 你的 Fork git clone https://github.com/你的帳號/FinceptTerminal.git cd FinceptTerminal # 3. 建立新的功能分支 git checkout -b feature/你的功能名稱 # 4. 進行修改... # 5. 提交變更 git add . git commit -m "feat: 加入某某功能的說明" # 6. 推送到你的 Fork git push origin feature/你的功能名稱 # 7. 在 GitHub 上開啟 Pull Request

目前期待的貢獻項目

• 新增更多上櫃股票到參考清單
• 加入台灣 ETF 完整清單
• 支援期貨/選擇權資料（TAIFEX 臺灣期貨交易所）
• 加入英文版 README（README.md）
• 補充更多技術指標範例

程式碼風格

• 所有函式需有 docstring（中英文均可）——連接器現有函式均已遵循此規範，可作為範本
• 新增功能請附上測試範例
• 檔案頂部須保留原始授權聲明

總結

本文完整介紹了 FinceptTerminal 台灣股市資料連接器的設計與用法：它是一個純 Python 層的輕量擴充，透過 Yahoo Finance 與 TWSE 官方 OpenAPI 兩條免費資料通道，為終端補上「上市/上櫃個股歷史行情、公司基本面、大盤指數、市場概況、強勢股排行、股票搜尋、完整清單」七類能力，並內建了保守的限速邏輯與可一鍵執行的自我測試。無論你是想要在終端介面中直接查詢台股的使用者，還是打算進一步擴充台灣市場資料（如 TAIFEX 期貨選擇權、ETF 清單）的開發者，都可以從這份指南與連接器源碼出發，快速上手。

【免费下载链接】FinceptTerminalFinceptTerminal is a modern finance application offering advanced market analytics, investment research, and economic data tools, designed for interactive exploration and>项目地址: https://gitcode.com/GitHub_Trending/fi/FinceptTerminal