開發者文件

Python SDK

clarifindata-python 是官方 Python SDK，自動處理分頁、retry、pandas 整合。

安裝

bash

pip install clarifindata

Python 3.8+ 支援。依賴 requests 和 pandas（可選）。

快速上手

python

from clarifindata import Client

# Replace with your API key from https://clarifindata.com/dashboard
cfd = Client("YOUR_API_KEY")

# Fetch OHLCV for TSMC (2330) — returns a pandas DataFrame
df = cfd.get("TaiwanStockPrice", stock_id="2330", start_date="2026-01-01")
print(df.head())

輸出

text

  stock_id  trade_date     open     high      low    close    volume
0     2330  2026-01-02  1080.00  1090.00  1075.00  1085.00  18200000
1     2330  2026-01-03  1085.00  1095.00  1080.00  1090.00  21100000
...

進階範例

批次查詢多支股票

python

# Comma-separated stock_id for batch queries
df = cfd.get(
    "TaiwanStockPrice",
    stock_id="2330,2317,0050",
    start_date="2026-01-01",
    end_date="2026-06-11",
)
print(df.groupby("stock_id")["close"].last())

查詢財報（季）

python

# Financial statements — period=quarterly (default)
df = cfd.get(
    "TaiwanStockFinancialStatement",
    stock_id="2330",
    period="quarterly",
)
print(df[["date", "revenue", "net_income", "eps"]])

自然語言查詢（Plus）

python

# Plus-tier key required
result = cfd.ask("2330 在 2026 年 Q1 最高收盤價是哪天？")
print(result["sql"])
print(result["data"])

大量歷史資料（自動分頁）

python

# The SDK handles cursor-based pagination automatically
df = cfd.get_all(
    "TaiwanStockInstitutionalInvestorsBuySell",
    stock_id="2330",
)
print(f"{len(df):,} rows fetched")

✓

cfd.get() 預設回傳 pandas DataFrame。傳入 raw=True 可改回原始 dict。

設定

python

from clarifindata import Client

cfd = Client(
    api_key="YOUR_API_KEY",
    base_url="https://api.clarifindata.com",  # default
    timeout=30,                                # seconds
    max_retries=3,                             # on 429 / 5xx
)