開發者文件

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。此參數僅適用於含 stock_id 欄位的資料集。
`start_date`	string	否	起始日，YYYY-MM-DD，含當天
`end_date`	string	否	結束日，YYYY-MM-DD，含當天
`limit`	integer	否	回傳筆數上限，最大 10,000(預設: 1000)
`cursor`	string	否	分頁游標，請帶入上一個回應的 cursor 值。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 方案限定。請求可使用中文或英文自然語言問題；服務會以 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 key。使用 Free 或 Lite key 呼叫時會回傳 403。

GET /v1/key/info

GET/v1/key/info

回傳此 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": "[email protected]",
  "tier": "lite",
  "created_at": "2026-03-15T08:12:00Z"
}