Building an AI agent? Start with /llms.txt for the full site index.

公司與事件

股利資料

提供台股公司的股利分配資料，適合用於殖利率分析、總報酬計算與股利策略研究。

This documentation page is currently available in Chinese only; English versions are coming soon.

GET/v2/datasets/dividends

Overview

股利資料 API 提供公司對股東的分配資訊，包含現金股利、股票股利與相關除權息事件資料。這類資料適合用於股利策略、報酬分析與長期持有研究。

與一般公告或事件資料不同，股利資料的核心價值在於可量化的股東回報資訊。

它不只是事件發生與否，而是可以直接影響殖利率、持有報酬與價格調整邏輯的資料。

典型用途包括：

計算現金殖利率
建立總報酬與股利再投資研究
驗證除權息前後價格表現
將股利資料納入因子、選股或長期持有策略
與公司行動、價格資料一起交叉檢查權益調整
如果公司行動頁面偏向哪些事件會影響資料處理，股利資料頁面則更聚焦於股東實際收到的分配與對報酬的影響。

Coverage

Instruments	Start year	Update timing	Includes delisted
Not yet available (coming)	Not yet available (coming)	Not yet available (coming)	coming

Figures are measured from the DB; unlisted fields defer to docs coverage (coming) — we don't fabricate cell by cell.

Request

使用此 endpoint 時，建議：

Query Parameters

欄位	型別	Required	說明
symbol	string	yes	股票代碼，用於查詢單一公司的股利資料。
start_date	string	no	查詢起始日期。
end_date	string	no	查詢結束日期。
dividend_type	string	no	股利類型（若目前 schema 有正式支持）。
limit	integer	no	回傳筆數限制。
offset	integer	no	分頁偏移。

Response Shape

所有回應遵循一致結構，包含 dataset、source_role、freshness、lineage、data。

{  "dataset": "dividends",  "source_role": "canonical",  "freshness": "2026-04-22T11:15:00+08:00",  "lineage": {    "source": "TWSE",    "ingested_at": "2026-04-22T11:15:05+08:00",    "trace_id": "dividends_2330_20260422"  },  "data": [    {      "ticker": "2330",      "event_date": "2025-06-12",      "dividend_type": "cash_dividend",      "cash_amount": 3.5,      "title": "現金股利除息"    }  ]}

Field 說明

欄位路徑	型別	說明
data[].ticker	string	股票代碼。
data[].event_date	string	股利事件日期或除權息相關日期。
data[].dividend_type	string	股利類型，例如現金股利或股票股利。
data[].cash_amount	number\|null	現金股利金額（若目前 schema 有）。
data[].stock_ratio	number\|string\|null	股票股利比例（若目前 schema 有）。
data[].title	string\|null	事件標題（若目前 schema 有）。
data[].source_url	string\|null	原始來源連結（若目前 schema 有）。
source_role	string	資料來源角色。
freshness	string	資料更新時間。
lineage.trace_id	string	可追蹤資料處理鏈路。

Usage Notes / 使用建議

使用 ticker + event_date + dividend_type 作為主要識別組合。
若要做殖利率分析，應保留現金股利金額與除息時間。
若要做總報酬研究，應與還原價格或公司行動資料一起使用。
對長期研究建議先完整抓取並落地，不要重複即時查詢。
若只需要查看是否有事件發生，應改用事件日曆；若要做權益調整，應搭配公司行動頁面。

Limitations & notes

Coverage is not the full market or full history; the actual range is defined by the coverage table above and the data_gaps in the response.
Missing data is flagged honestly — we don't fill gaps with estimated values.
The platform focuses on daily-frequency and fundamental data; it does not provide real-time quotes, intraday bars, or cryptocurrencies.
TWSE is the verified baseline; TPEx history depth and adjusted prices are currently beta / deferred, flagged per dataset.

Plan Requirement

Free（限制）
Developer
Pro
Enterprise

此 API 屬於 TW Market Data 資料集目錄。查看資料集總覽

請求與回應

Request example

curl --request GET \  --url "https://api.twmarketdata.com/v2/datasets/dividends?symbol=2330&start_date=2024-01-01&end_date=2026-04-30&limit=20" \  --header "X-API-Key: your_api_key_here"

Status codes

成功回傳股利資料

JSON

{  "dataset": "dividends",  "source_role": "canonical",  "freshness": "2026-04-22T11:15:00+08:00",  "lineage": {    "source": "TWSE",    "ingested_at": "2026-04-22T11:15:05+08:00",    "trace_id": "dividends_2330_20260422"  },  "data": [    {      "ticker": "2330",      "event_date": "2025-06-12",      "dividend_type": "cash_dividend",      "cash_amount": 3.5,      "title": "現金股利除息"    }  ]}