clarifindata — Python client

Python client for the 金晰數據 / clarifindata Taiwan-stock data API (83 datasets: prices, chips, fundamentals, derivatives, macro — full history, refreshed daily).

pip install clarifindata            # core
pip install 'clarifindata[pandas]'  # + DataFrame output (as_df=True)
pip install 'clarifindata[all]'     # + pandas + HTTP/2

Quickstart

from clarifindata import Client, datasets

cfd = Client(api_key="cfd_demo_free_0001")          # free demo key

# typed dataset names (autocomplete + typo-safe), DataFrame output
df = cfd.get(datasets.TaiwanStockPrice, stock_id="2330",
             start="2026-04-01", end="2026-06-03", as_df=True)
print(df.head())

Demo keys (rate-limited, for trying out): cfd_demo_free_0001 (Free), cfd_demo_lite_0001 (Lite). Get your own at https://clarifindata.com/signup.

Features

Full history (any range, no manual chunking)

for batch in cfd.iter_history(datasets.TaiwanStockPrice, stock_id="2330", since="2015-01-01"):
    process(batch)                                  # one year per batch, streamed

df = cfd.history(datasets.TaiwanStockPrice, stock_id="2330", since="2015-01-01", as_df=True)

Concurrency (fetch many stocks)

import asyncio
from clarifindata import AsyncClient, datasets

async def main():
    async with AsyncClient(api_key="...") as cfd:
        tasks = [cfd.get(datasets.TaiwanStockPrice, stock_id=s, as_df=True)
                 for s in ("2330", "2317", "2454")]
        return await asyncio.gather(*tasks)

frames = asyncio.run(main())

Natural-language queries (Plus tier)

ans = cfd.ask("找出 2330 在 2026 年 4 月最高收盤價那天", as_df=True)

Errors

from clarifindata import TierError, RateLimitError, ValidationError
try:
    cfd.get("TaiwanStockPirce")          # typo
except ValidationError as e:
    print(e)        # Unknown dataset 'TaiwanStockPirce'. Did you mean 'TaiwanStockPrice'? ...