開發者文件

REST API 參考

所有 endpoint 的完整說明，包含參數、範例請求與回應、錯誤碼。Base URL: https://api.clarifindata.com

取得資料集目錄

GET/v1/data

列出所有可用的資料集，包含名稱、tier、分類、欄位、說明、口徑說明、覆蓋範圍（第一筆 / 最後一筆 / 筆數）。

參數名稱	型別	必填	說明
`category`	string	否	篩選分類：technical / chips / fundamentals / derivatives / convertibles / other
`tier`	string	否	篩選 tier：free / lite / plus

範例請求

bash

curl -H "Authorization: Bearer YOUR_API_KEY" \
     "https://api.clarifindata.com/v1/data"

回應 — 200 OK（節錄）

json

{
  "datasets": [
    {
      "name": "TaiwanStockPrice",
      "table": "taiwan_stock_price",
      "tier": "free",
      "category": "technical",
      "status": "live",
      "description": "上市櫃股票日 K（TWSE/TPEx STOCK_DAY）",
      "columns": ["stock_id","trade_date","open","high","low","close","volume","turnover","trade_count","spread"],
      "key_date_column": "trade_date",
      "update_freq": "daily",
      "supports_stock_id": true,
      "unit": null,
      "notes": null,
      "adjustment_method": null,
      "odd_lot_included": null,
      "accumulation": null,
      "example_query": "/v1/data/TaiwanStockPrice?stock_id=2330&limit=5",
      "coverage": {
        "first_date": "2004-01-02",
        "last_date": "2026-06-11",
        "row_count": 9800000
      }
    }
  ]
}

查詢資料集

GET/v1/data/{dataset}

從指定資料集查詢資料列。{dataset} 為資料集名稱（例如 TaiwanStockPrice）。

ℹ

回應的 cursor 欄位為 null 表示已到最後一頁。帶入 cursor 參數可繼續翻頁。limit 最大 10,000。

參數名稱	型別	必填	說明
`stock_id`	string	否	股票代號（例如 2330）。多個股票用逗號分隔：2330,2317,0050。支援的資料集才有效。
`start_date`	string	否	起始日期，格式 YYYY-MM-DD（含）
`end_date`	string	否	結束日期，格式 YYYY-MM-DD（含）
`limit`	integer	否	回傳筆數上限，最大 10,000(預設: 1000)
`cursor`	string	否	分頁游標，從上一次回應的 cursor 欄位取得。null 表示最後一頁。
`period`	string	否	對支援財務週期的資料集（如財報）指定 quarterly 或 annual
`include_expired`	boolean	否	可轉債資料集：是否包含到期/終止的可轉債(預設: false)
`include_inactive`	boolean	否	是否包含已下市的股票(預設: false)
`aggregate`	string	否	聚合方式，目前保留欄位（未來功能）

範例：查詢單一股票

bash

curl -H "Authorization: Bearer YOUR_API_KEY" \
     "https://api.clarifindata.com/v1/data/TaiwanStockPrice?stock_id=2330&start_date=2026-01-01&end_date=2026-06-11&limit=10"

範例：批次查詢多支股票

bash

curl -H "Authorization: Bearer YOUR_API_KEY" \
     "https://api.clarifindata.com/v1/data/TaiwanStockPrice?stock_id=2330,2317,0050&limit=100"

回應 — 200 OK

json

{
  "dataset":   "TaiwanStockPrice",
  "tier_used": "free",
  "count":     10,
  "data": [
    {
      "stock_id":    "2330",
      "trade_date":  "2026-06-11",
      "open":        "1020.0000",
      "high":        "1025.0000",
      "low":         "1015.0000",
      "close":       "1020.0000",
      "volume":      15384000,
      "turnover":    "15691680000",
      "trade_count": 28441,
      "spread":      "10.0000"
    }
  ],
  "cursor": null
}

分頁範例

python

import requests

def fetch_all(dataset, api_key, **params):
    headers = {"Authorization": f"Bearer {api_key}"}
    url = f"https://api.clarifindata.com/v1/data/{dataset}"
    rows = []
    cursor = None
    while True:
        p = {**params, "limit": 10000}
        if cursor:
            p["cursor"] = cursor
        resp = requests.get(url, headers=headers, params=p).json()
        rows.extend(resp["data"])
        cursor = resp.get("cursor")
        if not cursor:
            break
    return rows

自然語言查詢

Plus

POST/v1/ask

Plus 方案專屬。傳入自然語言問題（中文或英文），API 以 DeepSeek 模型翻譯成 SQL，在唯讀沙箱執行後回傳結果。

參數名稱	型別	必填	說明
`question`	string	是	自然語言問題，中英文皆可。例如：「2330 在 2026 年 Q1 最高收盤價是哪天？」
`max_rows`	integer	否	回傳筆數上限（1–1000）(預設: 100)

範例請求

bash

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

回應 — 200 OK

json

{
  "question": "2330 在 2026 年 Q1 的最高收盤價是哪天？",
  "sql":    "SELECT trade_date, close FROM taiwan_stock_price WHERE stock_id='2330' AND trade_date BETWEEN '2026-01-01' AND '2026-03-31' ORDER BY close DESC LIMIT 1",
  "engine": "clarifindata-ask-v1",
  "count":  1,
  "data":   [{ "trade_date": "2026-01-22", "close": "1095.0000" }]
}

⚠

POST /v1/ask 只在 Plus tier 可用。用 Free 或 Lite key 呼叫會回 403。

GET /v1/key/info

GET/v1/key/info

查詢目前 API Key 的 tier、每小時配額、剩餘次數、視窗剩餘時間。

bash

curl -H "Authorization: Bearer YOUR_API_KEY" \
     "https://api.clarifindata.com/v1/key/info"

json

{
  "tier": "lite",
  "rate_limit_per_hour": 3000,
  "remaining_this_hour": 2947,
  "window_resets_in_seconds": 1823
}

GET /v1/me

GET/v1/me

查詢目前登入帳號的基本資訊（tier、email、加入日期）。需要 session cookie（瀏覽器已登入），或以 Bearer token 認證。

bash

curl -H "Authorization: Bearer YOUR_API_KEY" \
     "https://api.clarifindata.com/v1/me"

json

{
  "user_id": 42,
  "email": "user@example.com",
  "tier": "lite",
  "created_at": "2026-03-15T08:12:00Z"
}