金晰數據
API 文件

三分鐘上手

一個 base URL, 一個 header. 回應永遠是 JSON, 欄位命名永遠一致, 直接餵進 pandas.

BASEhttps://clarifindata.com/api

01·認證

認證

只接受一種方式 — Authorization Bearer (RFC 6750, 跟 Stripe / OpenAI 一樣). 把下面範例裡的 YOUR_FREE_KEY 換成你在 /dashboard 註冊後拿到的 key.

curl -H "Authorization: Bearer YOUR_FREE_KEY" \
     "https://clarifindata.com/api/v1/data/TaiwanStockPrice?stock_id=2330&limit=5"

每筆回應都帶 X-RateLimit-* header. 公開頁面沒有 demo key — 註冊就有自己的 Free key, 不會被惡意流量打到上限.

02·查資料

查資料

通用格式: /v1/data/{dataset_name}. Free 等級的 key 能直接拿 free 資料集; Lite / Plus 資料集需要對應等級的 key.

請求 — 複製貼進終端機可直接執行

curl -H "Authorization: Bearer YOUR_FREE_KEY" \
  "https://clarifindata.com/api/v1/data/TaiwanStockPrice?stock_id=2330&start=2026-04-01&end=2026-04-30"

回應 — 200 OK

{
  "dataset": "TaiwanStockPrice",
  "tier_used": "free",
  "count": 20,
  "data": [
    {
      "stock_id":    "2330",
      "trade_date":  "2026-04-30",
      "open":        "2205.0000",
      "high":        "2215.0000",
      "low":         "2135.0000",
      "close":       "2135.0000",
      "volume":      59584011,
      "turnover":    "129218504000",
      "trade_count": 41882,
      "spread":      "-70.0000"
    }
  ]
}
03·自然語言查詢

自然語言查詢

Plus 方案. POST /v1/ask, body 帶 question, 我們 LLM 出 SQL, 跑完回給你. 中英文都通.

請求 — 把 YOUR_PLUS_KEY 換成你的 Plus key

curl -X POST \
     -H "Authorization: Bearer YOUR_PLUS_KEY" \
     -H "Content-Type: application/json" \
     -d '{"question": "2330 在 2026 年 4 月最高收盤價是哪天"}' \
     https://clarifindata.com/api/v1/ask

回應 — 200 OK

{
  "question": "2330 在 2026 年 4 月最高收盤價是哪天",
  "sql": "SELECT trade_date, close FROM taiwan_stock_price
          WHERE stock_id = '2330'
            AND trade_date BETWEEN '2026-04-01' AND '2026-04-30'
          ORDER BY close DESC LIMIT 1",
  "engine": "clarifindata-ask-v1",
  "count":  1,
  "data":   [ { "trade_date": "2026-04-27", "close": "2265.0000" } ]
}
04·速率限制

速率限制

Free
600 / hr
demo / 試玩
Lite
3,000 / hr
個人 backtest
Plus
10,000 / hr
團隊 / 商用

超過限制回 429, body 帶 retry_after_seconds. 隨機散開重試即可.

05·資料集

資料集

73 個資料集全部已 live、皆有真實資料，每日自動更新。下面是常用的幾個；完整清單（含資料範圍與缺漏說明）在 /datasets。

01TaiwanWeightedIndexfree台股加權指數 OHLC
02TaiwanStockPERfree個股 PER / PBR / 殖利率
03TaiwanStockFinancialStatementfree綜合損益表 — 每季 EPS/營收/淨利
04TaiwanStockPricelite個股日 K (TWSE STOCK_DAY)
05TaiwanStockInstitutionalInvestorsBuySelllite個股三大法人買賣超 (TWSE T86)
06TaiwanStockMarginRatiolite大盤融資維持率 — 完整回溯 2012
07TaiwanStockPriceAdjplus還原股價 — 除權息調整
08TaiwanStockMonthRevenuelite月營收表

完整清單在 /datasets；機器可讀 schema 在 /llms.txt（給 AI agent 用，也是最權威來源）。

06·服務狀態

服務狀態

走 /healthz 看 API / Postgres / Kafka / MinIO 是否都活著, 回 JSON 易讀.