台股歷史股價 API 設計：K 線、除權息、調整後收盤價與回測資料

為什麼歷史股價 API 對台股量化交易重要？

台股量化研究通常不是從模型開始，而是從資料開始。策略訊號、回測績效、風險指標和 AI agent 的分析結果，都依賴歷史資料是否乾淨、完整且可重複取得。

如果歷史資料 API 不穩定，後續會出現幾種常見問題：

• 同一檔股票不同時間查詢結果不一致
• 欄位名稱或型別在不同 endpoint 中不一致
• 日期格式混用
• 成交量單位不清楚
• 沒有處理除權息
• 下市股票消失，造成 survivorship bias
• 停牌、無成交或缺值沒有標示
• 沒有交易日曆，導致回測日期對齊錯誤

如果你剛開始了解台股 API 的資料類型，可以先看 台股 API 完整指南。

如果你已經要用 Python 抓資料，可以參考 Python 抓台股資料教學。

如果你想把歷史資料進一步接到策略回測與風險控管，可以再看 台股量化交易入門。

如果你要把 OHLCV 進一步轉成均線、RSI、MACD 或布林通道等指標，可再看 台股技術分析 API。

OHLCV 是什麼？

OHLCV 是歷史股價最基本的資料格式，代表：

對大多數回測、技術分析和因子研究來說，OHLCV 是最低限度資料。但台股 API 只提供 OHLCV 還不夠，還需要至少補上：

• symbol
• market
• date
• turnover
• currency
• adjusted flag
• data source
• timezone

{
  "date": "2026-04-23",
  "symbol": "2330",
  "market": "twse",
  "open": 812,
  "high": 825,
  "low": 808,
  "close": 821,
  "volume": 35124000,
  "turnover": 28754100000,
  "currency": "TWD"
}

日 K、週 K、月 K 怎麼設計？

台股歷史股價 API 常見查詢粒度包括日 K、週 K 和月 K。這些資料可以由 API 直接提供，也可以由 client 端根據日 K 聚合。

如果由 API 直接提供週 K 或月 K，應清楚說明聚合規則。通常：

• open 取期間第一個交易日開盤價
• high 取期間最高價
• low 取期間最低價
• close 取期間最後一個交易日收盤價
• volume 取期間成交量加總
• turnover 取期間成交金額加總

GET /v1/tw/stocks/{symbol}/ohlcv?interval=1d&from=2025-01-01&to=2025-12-31
GET /v1/tw/stocks/{symbol}/ohlcv?interval=1w&from=2025-01-01&to=2025-12-31
GET /v1/tw/stocks/{symbol}/ohlcv?interval=1mo&from=2020-01-01&to=2025-12-31

除權息與調整後收盤價

台股長期回測不能忽略除權息。當公司配發現金股利、股票股利、減資或發生其他 corporate actions 時，未調整價格和調整後價格會產生差異。

如果使用未調整價格做長期策略研究，可能會把除權息造成的價格變化誤判成市場價格下跌，進而影響：

• 報酬率計算
• 技術指標
• 動能策略
• 最大回撤
• 長期績效
• AI agent 對價格走勢的解讀

GET /v1/tw/stocks/2330/ohlcv?from=2020-01-01&to=2025-12-31&adjusted=false
GET /v1/tw/stocks/2330/ohlcv?from=2020-01-01&to=2025-12-31&adjusted=true

{
  "data": [
    {
      "date": "2026-04-23",
      "symbol": "2330",
      "open": 812,
      "high": 825,
      "low": 808,
      "close": 821,
      "volume": 35124000,
      "turnover": 28754100000
    }
  ],
  "meta": {
    "adjusted": false,
    "timezone": "Asia/Taipei",
    "currency": "TWD"
  }
}

歷史資料 API response schema

歷史資料 API 的 response schema 應該同時支援人類閱讀和程式消費。建議至少包含 `data` 和 `meta` 兩層。

{
  "data": [
    {
      "date": "2026-04-23",
      "symbol": "2330",
      "market": "twse",
      "open": 812,
      "high": 825,
      "low": 808,
      "close": 821,
      "volume": 35124000,
      "turnover": 28754100000,
      "currency": "TWD"
    }
  ],
  "meta": {
    "source": "tw-market-data",
    "interval": "1d",
    "adjusted": false,
    "from": "2026-04-01",
    "to": "2026-04-23",
    "timezone": "Asia/Taipei"
  }
}

回測資料常見偏誤

歷史股價資料最危險的地方，是它看起來很完整，但實際上可能已經帶有偏誤。這些偏誤會讓回測結果看起來比真實情況更好。

如何查詢一段時間的歷史資料？

台股歷史股價 API 應該支援清楚的時間區間查詢。最常見的方式是使用 `from` 和 `to` 參數。

GET /v1/tw/stocks/2330/ohlcv?from=2025-01-01&to=2025-12-31

對大量資料來說，還需要考慮 pagination、batch query 和 rate limit。

POST /v1/tw/stocks/ohlcv/batch

{
  "symbols": ["2330", "2317", "2454"],
  "from": "2025-01-01",
  "to": "2025-12-31",
  "interval": "1d",
  "adjusted": true
}

如何把歷史股價 API 接到 Python？

以下示範如何用 Python 抓取一檔股票的歷史 OHLCV，並轉成 pandas DataFrame。

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 = {
    "from": "2025-01-01",
    "to": "2025-12-31",
    "interval": "1d",
    "adjusted": "true"
}

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

response.raise_for_status()

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

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

print(df.head())

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

meta = payload.get("meta", {})

if not meta.get("adjusted"):
    print("Warning: data is not adjusted. Long-term backtest may be affected by corporate actions.")

如何把歷史資料接進回測系統？

歷史股價 API 回傳的 DataFrame 可以直接接進 backtester。最低限度需要 date、symbol、close 和 volume。

df["return"] = df["close"].pct_change()
df["ma20"] = df["close"].rolling(20).mean()
df["ma60"] = df["close"].rolling(60).mean()

df["signal"] = (df["ma20"] > df["ma60"]).astype(int)
df["strategy_return"] = df["signal"].shift(1) * df["return"]

equity_curve = (1 + df["strategy_return"].fillna(0)).cumprod()

print(equity_curve.tail())

這只是資料處理示意，不是投資策略建議。正式回測還需要：

• 交易成本
• 滑價
• position sizing
• 風險限制
• 停損或部位調整規則
• out-of-sample test
• walk-forward validation
• portfolio-level analysis

AI agent 如何使用歷史股價資料？

AI agent 不應該靠模型內部知識猜測股價，也不應該直接把未驗證的自然語言當成市場資料。正確做法是讓 agent 透過 tool calling 查詢台股歷史資料。

{
  "name": "get_historical_ohlcv",
  "description": "Get historical OHLCV data for a Taiwan stock.",
  "parameters": {
    "symbol": "2330",
    "from": "2025-01-01",
    "to": "2025-12-31",
    "interval": "1d",
    "adjusted": true
  }
}

{
  "symbol": "2330",
  "data_used": [
    "historical_ohlcv"
  ],
  "price_adjusted": true,
  "summary": "The stock showed positive momentum over the selected period, but further risk checks are required.",
  "risk_flags": [
    "requires_volume_liquidity_check",
    "strategy_not_backtested"
  ],
  "not_investment_advice": true
}

建議的 endpoint 設計

以下是歷史股價相關 endpoint 的設計示意。

GET /v1/tw/stocks/{symbol}/ohlcv
GET /v1/tw/stocks/{symbol}/ohlcv?interval=1d
GET /v1/tw/stocks/{symbol}/ohlcv?interval=1w
GET /v1/tw/stocks/{symbol}/ohlcv?interval=1mo
GET /v1/tw/stocks/{symbol}/ohlcv?adjusted=true
GET /v1/tw/stocks/{symbol}/corporate-actions
GET /v1/tw/calendar/trading-days

實際 endpoint 命名不一定要完全相同。重點是查詢參數清楚、response schema 穩定、價格調整狀態明確，並且能支援回測和資料管線。

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