FinMind API 串接台股歷史價量與除權息：Python / 前端數據工程介接實踐

對於想要進行台股程式化量化分析、歷史策略回測，或是希望在個人記帳 App 中自動更新台股即時與歷史報價的開發者而言，FinMind 金融數據資料庫 是一個極其優質且對社群非常友好的開放平台。

FinMind 提供了乾淨且格式統一的 RESTful API 介面，涵蓋台股個股日成交資訊、三大法人買賣超、融資融券異動、綜合損益表與股利分派歷史等超過 50 種資料集（Datasets）。本文將詳細介紹如何免費申請 API Token、常用台股 Dataset 結構對照表，以及如何在前端（JavaScript）與後端（Python）中穩定介接並處理頻率限制（Rate Limits）。

一、 3 步驟免費取得 FinMind API Token 與配額說明

1. 前往 FinMind 官方網站（finmindtrade.com）點擊右上角「註冊 / 登入」。
2. 完成 Email 帳號驗證後，登入會員後台管理面板（Dashboard）。
3. 在「API Token 簽發區」點擊生成並複製屬於您的專屬 API Token（Bearer / Query 參數皆可使用）。

二、 台股投資記帳與回測必備的 5 大 Dataset 對照表

FinMind v4 API 採用統一端點 https://api.finmindtrade.com/api/v4/data，只需切換 dataset 參數即可取得不同維度的台股數據：

三、 JavaScript 與 Python 實戰介接範例（股價與除權息查詢）

1. 前端 JavaScript (Fetch API) 查詢台積電 (2330) 歷史收盤價：

async function fetchTaiwanStockPrice(stockId, startDate, token) {
  const params = new URLSearchParams({
    dataset: 'TaiwanStockPrice',
    data_id: stockId,
    start_date: startDate,
  });

  const response = await fetch(`https://api.finmindtrade.com/api/v4/data?${params}`, {
    headers: { Authorization: `Bearer ${token}` },
  });

  if (!response.ok) {
    throw new Error(`HTTP 錯誤狀態碼: ${response.status}`);
  }

  const result = await response.json();
  if (result.status !== 200) {
    throw new Error(`FinMind API 回應錯誤: ${result.msg}`);
  }
  return result.data; // 回傳每日開高低收陣列
}

2. 後端 Python 擷取個股除權息歷史紀錄並轉為 Pandas DataFrame：

import requests
import pandas as pd

def get_dividend_history(stock_id: str, token: str) -> pd.DataFrame:
    url = "https://api.finmindtrade.com/api/v4/data"
    params = {
        "dataset": "TaiwanStockDividendResult",
        "data_id": stock_id,
        "start_date": "2020-01-01",
    }
    headers = {"Authorization": f"Bearer {token}"}
    resp = requests.get(url, params=params, headers=headers, timeout=10)
    data = resp.json()
    return pd.DataFrame(data.get("data", []))

四、 數據工程實務：快取策略與常見錯誤排解

• HTTP 402 / 429 配額耗盡處理：當短時間內迴圈抓取上百檔股票時，容易觸發每小時 600 次上限。建議在個人記帳工具中採用「本地優先快取（Local-First Caching）」——歷史已收盤的日期與已發生的除權息紀錄屬於不可變數據（Immutable Data），抓過一次即寫入本地 IndexedDB 或 SQLite，後續僅需針對「最新一個交易日」做增量查詢。
• 成交量單位換算：請特別留意 TaiwanStockPrice 回傳的 Trading_Volume 單位為「股（Shares）」而非「張（Lots）」。若欲換算為台股習慣的成交張數，需除以 1,000。
• 與 Stoxer 的整合方式：在 Stoxer App 的「系統設定 → 報價 API 授權」中，您可以選擇填入個人的 FinMind API Key (台股)。當您在首頁「累積資產成長曲線圖」點擊「同步股價」時，系統將直接在您的瀏覽器本地端向 FinMind 查詢歷史收盤價並快取於本地 IndexedDB，API Key 僅保存在您的瀏覽器本地端，絕不經過第三方後端伺服器。