台股財報 API 教學：用營收、EPS、ROE 與現金流建立基本面因子

為什麼台股財報 API 重要？

台股資料產品如果只提供股價，通常只能支援價格型分析、技術指標和部分回測需求。若要建立更完整的 financial data API，財報與基本面資料是必要的一層。

財報 API 可以支援：

• 基本面選股
• 量化因子研究
• 估值模型
• 月營收追蹤
• 財務比率分析
• 產業比較
• dashboard 報表
• AI agent 股票研究助理

股價資料回答的是市場價格如何變動。財報資料回答的是公司營運與財務狀況如何變化。

如果你還在理解台股資料 API 的整體架構，可以先看 台股 API 完整指南。

財報資料有哪些類型？

台股基本面資料通常可以拆成幾個主要類型。不同資料的更新頻率、欄位格式和適用情境都不同。

月營收、季報與年報的差異

月營收、季報和年報不應該混在同一個資料模型裡。它們代表不同的時間粒度，也適合不同的研究問題。

損益表 API schema

損益表用來描述公司在特定期間的收入、成本、費用與獲利能力。API schema 應該清楚標示公司、期間、公告日、幣別與單位。

{
  "data": [
    {
      "symbol": "2330",
      "market": "twse",
      "period": "2025Q4",
      "announcement_date": "2026-03-15",
      "currency": "TWD",
      "unit": "thousand",
      "revenue": 625000000,
      "gross_profit": 330000000,
      "operating_income": 285000000,
      "net_income": 238000000,
      "eps": 9.21
    }
  ],
  "meta": {
    "source": "tw-market-data",
    "statement": "income_statement",
    "version": "latest"
  }
}

資產負債表 API schema

資產負債表描述公司在某個時間點的資產、負債與股東權益。它不是期間型資料，而是時間點資料。

{
  "data": [
    {
      "symbol": "2330",
      "period": "2025Q4",
      "announcement_date": "2026-03-15",
      "currency": "TWD",
      "unit": "thousand",
      "total_assets": 6200000000,
      "total_liabilities": 2400000000,
      "total_equity": 3800000000,
      "cash_and_equivalents": 1200000000,
      "inventory": 260000000,
      "accounts_receivable": 420000000
    }
  ],
  "meta": {
    "statement": "balance_sheet",
    "version": "latest"
  }
}

資產負債表常用於計算槓桿、流動性、資產品質與財務結構。例如 debt-to-equity、current ratio、inventory turnover 等。

現金流量表 API schema

現金流量表用來觀察公司現金如何流入與流出。對基本面研究來說，現金流通常比單純獲利數字更能反映財務品質。

{
  "data": [
    {
      "symbol": "2330",
      "period": "2025Q4",
      "announcement_date": "2026-03-15",
      "currency": "TWD",
      "unit": "thousand",
      "operating_cash_flow": 310000000,
      "investing_cash_flow": -180000000,
      "financing_cash_flow": -60000000,
      "capital_expenditure": -150000000,
      "free_cash_flow": 160000000
    }
  ],
  "meta": {
    "statement": "cash_flow_statement",
    "version": "latest"
  }
}

EPS、ROE 與常見基本面指標

財報 API 不一定只提供原始報表欄位，也可以提供由財報計算出的 ratios。但無論 ratios 是 API 預先計算，還是 client 端自行計算，都必須清楚定義公式與資料期間。

公告日比報表期更重要

在回測與量化研究裡，公告日通常比報表期更重要。

例如，一份 2025Q4 財報可能代表 2025 年第四季的營運結果，但它不會在 2025Q4 當下就被市場完整知道。如果回測系統在 2025 年底就使用這份財報資料，就會產生 look-ahead bias。

好的財報 API 應該至少區分：

• period
• fiscal_year
• fiscal_quarter
• announcement_date
• filing_date
• effective_date
• data_version

如何建立基本面因子？

基本面因子是把財報資料轉成可排序、可回測、可比較的數值。常見因子包括成長、獲利、品質、估值與財務風險。

{
  "date": "2026-04-24",
  "symbol": "2330",
  "factor_name": "revenue_growth_12m",
  "value": 0.18,
  "rank": 15,
  "universe": "twse_large_cap",
  "data_used": [
    "monthly_revenue",
    "announcement_date"
  ]
}

Python 串接財報 API 範例

以下示範如何用 Python 呼叫財報 API，取得損益表資料並計算簡單基本面指標。

import os
import requests
import pandas as pd

API_KEY = os.getenv("TW_MARKET_DATA_API_KEY")
BASE_URL = "https://api.example.com"

headers = {
    "Authorization": f"Bearer {API_KEY}"
}

params = {
    "symbol": "2330",
    "from": "2024Q1",
    "to": "2025Q4"
}

response = requests.get(
    f"{BASE_URL}/v1/tw/stocks/2330/financials/income-statement",
    headers=headers,
    params=params,
    timeout=20
)

response.raise_for_status()

payload = response.json()
df = pd.DataFrame(payload["data"])

df["announcement_date"] = pd.to_datetime(df["announcement_date"])
df = df.sort_values("announcement_date").reset_index(drop=True)

df["gross_margin"] = df["gross_profit"] / df["revenue"]
df["net_margin"] = df["net_income"] / df["revenue"]

print(df[["period", "announcement_date", "revenue", "eps", "gross_margin", "net_margin"]])

上方 endpoint 是示意。實際 API host 與路徑請以 TW Market Data docs 為準。

backtest_date = pd.Timestamp("2025-08-01")

available_financials = df[df["announcement_date"] <= backtest_date]

latest = available_financials.tail(1)

print(latest)

AI agent 如何使用財報資料？

AI agent 不應該靠模型內部知識猜 EPS、ROE 或營收。正確做法是讓 agent 透過 tool calling 查詢財報 API，再用 LLM 做摘要、比較、解釋和風險標記。

{
  "name": "get_financial_statements",
  "description": "Get financial statements for a Taiwan stock.",
  "parameters": {
    "symbol": "2330",
    "statement": "income_statement",
    "from": "2024Q1",
    "to": "2025Q4"
  }
}

{
  "symbol": "2330",
  "data_used": [
    "income_statement",
    "balance_sheet",
    "cash_flow_statement"
  ],
  "latest_period": "2025Q4",
  "announcement_date": "2026-03-15",
  "summary": "Revenue and EPS increased compared with the previous year, but valuation and industry cycle require additional checks.",
  "risk_flags": [
    "requires_peer_comparison",
    "requires_updated_market_price",
    "not_a_trading_signal"
  ],
  "not_investment_advice": true
}

這種格式讓 agent 的輸出更容易被 dashboard、risk manager 或下一個 workflow 使用。重點是 agent 要標示自己用了哪些資料，以及哪些資料還不足。

常見資料品質問題

財報資料比 OHLCV 更容易出現 schema 和時間問題。常見問題包括：

建議的 API endpoint 設計

以下是台股財報與基本面資料相關 endpoint 的設計示意。

GET /v1/tw/stocks/{symbol}/financials/income-statement
GET /v1/tw/stocks/{symbol}/financials/balance-sheet
GET /v1/tw/stocks/{symbol}/financials/cash-flow
GET /v1/tw/stocks/{symbol}/monthly-revenue
GET /v1/tw/stocks/{symbol}/financial-ratios
GET /v1/tw/stocks/{symbol}/fundamental-factors

實際 endpoint 命名不一定要完全相同。重點是資料期間、公告日、單位、幣別與 schema 必須清楚，才能支援量化研究、dashboard 和 AI agent workflow。

上方 endpoint 是示意。實際路徑請以 TW Market Data docs 為準。