台股 API 完整入門：上市、上櫃、ETF、財報與事件資料怎麼串

很多人第一次接台股 API，會先把看到的 endpoint 全部串一輪，想說資料先抓滿再整理。這個做法看起來很勤快，但實務上常常讓流程更混亂：欄位命名不一致、資料頻率不同、時間軸對不起來，最後很難回答「這個結果到底能不能信」。

真正有效率的做法，是先把最常用、最容易驗證的資料接成一條最小鏈路，再逐層擴充。你不需要一開始就寫完整交易系統，只要順序對，研究品質會立刻提升。

為什麼多數人會在第一步就走歪

新手最容易踩到的坑，不是 API 不夠多，而是先後順序錯了：先接事件、先接很多衍生欄位、先做複雜篩選，卻還沒確認基礎價格與時間對齊是否穩定。

你可以把資料導入想成蓋房子。價格資料是地基，還原與時間對齊是鋼筋，基本面是主結構，估值與事件才是裝潢。地基不穩，再漂亮的因子也會崩。

先把台股資料分成 4 層

上市、上櫃、ETF 在實務上怎麼分

「台股」在口語上是一個整體，但資料工程上不是。你至少要把上市（TWSE）、上櫃（TPEx）、ETF 分開看。這三者來源、商品特性、成交結構都不同。

最實用的做法是：每一筆資料都保留市場別與商品型別欄位，不要只靠 symbol 猜。這樣你在回測、彙總與風險統計時，才不會把不同商品混成同一類。

原始價格 vs 還原價格：怎麼選才不會失真

如果你只看當日行情，原始價格通常夠用。但一旦你要比較長期績效、做回測、看多年度報酬，還原價格幾乎是必選。

原因很簡單：股利、減資、拆併股會讓原始價格出現跳點，這些跳點不等於真實報酬。你如果直接用原始價格做長期比較，策略績效會被扭曲。

月營收、三大報表、估值資料各自適合什麼情境

• 月營收：快速檢查營運動能，適合做早期篩選。
• 損益表：看獲利結構，適合判斷成長品質與利潤壓力。
• 資產負債表：看財務穩健度，適合做風險底線檢查。
• 現金流量表：看現金創造能力，適合確認獲利是否可落地。
• 估值資料：做橫向比較，避免只看成長忽略價格。

這些資料最怕的不是缺值，而是時間錯位。月營收是月頻、財報是季頻、價格是日頻。若不先定義「市場當時可見資料」，很容易在研究裡用到未來資訊。

初學者可直接操作的最小資料組合

• 第一組：TWSE 日線、TPEx 日線、還原股價、公司基本資料
• 第二組：月營收、損益表、資產負債表、現金流量表
• 第三組：估值資料、技術指標、指數市場概況、公司公告

一個最小且可驗證的串接順序

1. 先打通價格查詢：確認 symbol、日期區間、上市/上櫃來源都可穩定查詢。
2. 加入還原價格：先用同一檔股票比對原始與還原差異，確認你知道差別從哪裡來。
3. 接月營收與財報：先做單一公司時間線對照，再擴到多公司。
4. 補估值與技術指標：建立第一版可篩選條件。
5. 最後接事件資料：用來補脈絡，而不是取代主判斷。

最小查詢範例

curl --request GET \
  --url "https://api.twmarketdata.com/v2/datasets/twse-daily-price?symbol=2330&start_date=2026-01-01&end_date=2026-04-30&limit=5" \
  --header "X-API-Key: your_api_key_here"

import requests

headers = {"X-API-Key": "your_api_key_here"}
response = requests.get(
    "https://api.twmarketdata.com/v2/datasets/monthly-revenue",
    headers=headers,
    params={
        "symbol": "2330",
        "limit": 6
    }
)
print(response.json())

每多接一種資料，先檢查三件事：欄位定義、時間對齊、能否與前一層資料接起來。

新手最常犯的 4 個錯（具體版）

1. 把 TWSE 與 TPEx 當成同一張表使用，沒有保留市場別欄位。
2. 用原始價格跑長期回測，沒有先檢查公司行動造成的價格跳點。
3. 財報公告與價格日期直接硬對，沒有先定義可觀測時間窗。
4. 一開始就抓 20+ datasets，結果任何一層都沒有做完整驗證。

接到研究與 AI workflow 的實務建議

當你穩定拿到價格、基本面、估值與事件後，下一步不是再加資料，而是把流程固定下來：先查哪些欄位、如何過濾、回應格式怎麼定義、每次研究如何可重複。

對 AI workflow 來說，最重要的不是「資料多」，而是「欄位穩定、命名一致、時間可對齊」。先做到這三件事，你的 agent 才會給出可檢查、可追溯的回答。

結語

台股 API 並不難接，難的是把資料接成可重複、可研究、可自動化的流程。你只要把順序抓對：先價格、再還原、再基本面、再估值指標、最後補事件，後面要擴公司數量、擴資料集，或接到 AI workflow，都會順很多。