文件

財報（Earnings）

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

財報

GET/v1/earnings

前往儀表板

Overview#

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

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

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 "ticker=2330" \
  --data-urlencode "latest=true"

欄位	型別	Required	說明
ticker	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 建立完整事件分析流程。

錯誤與邊界情況#

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

請求與回應

請求範例

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

狀態碼

成功回傳財報資料

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
    }
  ]
}

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 "ticker=2330" \ --data-urlencode "latest=true"

欄位	型別	Required	說明
ticker	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	實際值相對共識差異百分比。