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

Docs

財報（Earnings）

提供季度與年度財報結果與發佈節點資訊。

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

財報

GET/v1/earnings

前往儀表板

Overview

此 endpoint 提供公司季度或年度財報快照，包含營收、EPS、淨利、毛利與營業利益等核心欄位。

資料會依公告節點逐步補齊，初步揭露與完整財報欄位可能存在差異。

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 常見使用情境：

建立財報事件日歷，追蹤公告前後價格反應。
比較市場共識與實際公告值，評估 surprise 影響。
搭配財報三大表與股價資料建立基本面策略。

建議接入步驟：

1. 在 request header 帶入 X-API-Key: your_api_key_here。
2. 至少提供 ticker，必要時再加 period 或 latest 控制回傳範圍。
3. 先以單一公司驗證欄位，再擴展至批次查詢流程。

curl -G "https://api.twmd.example/v1/earnings" \  -H "X-API-Key: your_api_key_here" \  --data-urlencode "symbol=2330" \  --data-urlencode "latest=true"

欄位	型別	Required	說明
symbol	string	yes	公司代號，例如 2330。
period	string	no	財報期間，例如 2025-Q4 或 2025。
report_type	string	no	quarterly 或 annual；未提供時由系統依資料可用性回傳。
latest	boolean	no	true 時僅回傳最新一期。

Response

回應 data 為財報紀錄陣列，單筆資料對應一個公司與一個財報期間。

若欄位尚未在初次公告揭露，可能回傳 null，後續更新會反映在 lineage 與 freshness。

{  "dataset": "earnings",  "source_role": "canonical",  "lineage": {    "provider": "MOPS",    "trace_id": "earnings_2330_2025q4"  },  "data": [    {      "ticker": "2330",      "fiscal_period": "2025-Q4",      "report_type": "quarterly",      "announcement_date": "2026-02-14",      "revenue": 868461000000,      "gross_profit": 466512000000,      "operating_income": 382146000000,      "net_income": 346783000000,      "eps": 13.37,      "eps_surprise_pct": 2.8    }  ]}

Field 說明

欄位路徑	型別	說明
dataset	string	固定為 earnings。
source_role	string	來源角色標記（canonical、fallback、helper）。
lineage.provider	string	資料來源提供者識別。
data[].ticker	string	公司代號。
data[].fiscal_period	string	財報期間，例如 2025-Q4。
data[].announcement_date	string	公告日期。
data[].revenue	number\|null	營收欄位；部分初步公告可能缺值。
data[].eps	number\|null	每股盈餘。
data[].net_income	number\|null	淨利。
data[].eps_surprise_pct	number\|null	實際值相對共識差異百分比。

使用建議

初步公告通常先揭露主欄位，完整欄位會在後續正式揭露補齊。
若用於回測，請固定查詢時間點並保存當時回應，避免回看偏差。
建議搭配 /v2/datasets/income-statement 與 /v2/datasets/price-enhanced 建立完整事件分析流程。

錯誤與邊界情況

參數格式錯誤
認證失敗
查無對應財報

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.

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

請求與回應

Request example

curl -G "https://api.twmd.example/v1/earnings" \  -H "X-API-Key: your_api_key_here" \  --data-urlencode "symbol=2330" \  --data-urlencode "period=2025-Q4"

Status codes

成功回傳財報資料

JSON

{  "dataset": "earnings",  "source_role": "canonical",  "lineage": {    "provider": "MOPS",    "trace_id": "earnings_2330_2025q4"  },  "data": [    {      "ticker": "2330",      "fiscal_period": "2025-Q4",      "report_type": "quarterly",      "announcement_date": "2026-02-14",      "revenue": 868461000000,      "gross_profit": 466512000000,      "operating_income": 382146000000,      "net_income": 346783000000,      "eps": 13.37,      "eps_surprise_pct": 2.8    }  ]}

Instruments

Start year

Update timing

Includes delisted

Not yet available (coming)

coming

Request

此 endpoint 常見使用情境：

建立財報事件日歷，追蹤公告前後價格反應。

比較市場共識與實際公告值，評估 surprise 影響。

搭配財報三大表與股價資料建立基本面策略。

建議接入步驟：

1. 在 request header 帶入 X-API-Key: your_api_key_here。

2. 至少提供 ticker，必要時再加 period 或 latest 控制回傳範圍。

3. 先以單一公司驗證欄位，再擴展至批次查詢流程。

curl -G "https://api.twmd.example/v1/earnings" \  -H "X-API-Key: your_api_key_here" \  --data-urlencode "symbol=2330" \  --data-urlencode "latest=true"

欄位	型別	Required	說明
symbol	string	yes	公司代號，例如 2330。
period	string	no	財報期間，例如 2025-Q4 或 2025。
report_type	string	no	quarterly 或 annual；未提供時由系統依資料可用性回傳。
latest	boolean	no	true 時僅回傳最新一期。

Response

回應 data 為財報紀錄陣列，單筆資料對應一個公司與一個財報期間。

若欄位尚未在初次公告揭露，可能回傳 null，後續更新會反映在 lineage 與 freshness。

{  "dataset": "earnings",  "source_role": "canonical",  "lineage": {    "provider": "MOPS",    "trace_id": "earnings_2330_2025q4"  },  "data": [    {      "ticker": "2330",      "fiscal_period": "2025-Q4",      "report_type": "quarterly",      "announcement_date": "2026-02-14",      "revenue": 868461000000,      "gross_profit": 466512000000,      "operating_income": 382146000000,      "net_income": 346783000000,      "eps": 13.37,      "eps_surprise_pct": 2.8    }  ]}

Field 說明

欄位路徑	型別	說明
dataset	string	固定為 earnings。
source_role	string	來源角色標記（canonical、fallback、helper）。
lineage.provider	string	資料來源提供者識別。
data[].ticker	string	公司代號。
data[].fiscal_period	string	財報期間，例如 2025-Q4。
data[].announcement_date	string	公告日期。
data[].revenue	number\|null	營收欄位；部分初步公告可能缺值。
data[].eps	number\|null	每股盈餘。
data[].net_income	number\|null	淨利。
data[].eps_surprise_pct	number\|null	實際值相對共識差異百分比。

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.