公司與事件

股利資料

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

GET/v2/datasets/dividends

Overview#

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

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

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

典型用途包括：

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

Request#

使用此 endpoint 時，建議：

Query Parameters#

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

Plan Requirement#

Free（限制）
Developer
Pro
Enterprise

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

請求與回應

請求範例

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

狀態碼

成功回傳股利資料

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": "現金股利除息"    }  ]}

Overview#

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

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

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

典型用途包括：

計算現金殖利率

建立總報酬與股利再投資研究

驗證除權息前後價格表現

將股利資料納入因子、選股或長期持有策略

與公司行動、價格資料一起交叉檢查權益調整

如果公司行動頁面偏向哪些事件會影響資料處理，股利資料頁面則更聚焦於股東實際收到的分配與對報酬的影響。

Query Parameters#

欄位	型別	Required	說明
ticker	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 作為主要識別組合。

若要做殖利率分析，應保留現金股利金額與除息時間。

若要做總報酬研究，應與還原價格或公司行動資料一起使用。

對長期研究建議先完整抓取並落地，不要重複即時查詢。

若只需要查看是否有事件發生，應改用事件日曆；若要做權益調整，應搭配公司行動頁面。