財務與成長（Canonical）
財報資料（Canonical）
canonical/supplemental 財報查詢面，適用於低階契約與資料對齊流程。
GET
/v2/datasets/financialsOverview#
financials 是 canonical/supplemental surface，提供較低階、可組合的財報結構資料。
此 route 不是主公開產品頁；若要穩定對外整合，優先使用 `/v2/datasets/income-statement`。
- 需要 statement_type（income/balance/cash flow）共用查詢入口時。
- 內部或進階流程需直接讀 canonical envelope 時。
- 做欄位映射或 schema 對照測試時。
Request#
使用此 endpoint 時，請注意它與 productized endpoint 契約不同。
Query Parameters#
| 欄位 | 型別 | Required | 說明 |
|---|---|---|---|
| ticker | string | no | 股票代碼（canonical route 使用 ticker）。 |
| statement_type | string | no | income_statement / balance_sheet / cash_flow。 |
| period_type | string | no | quarterly / annual / ttm。 |
| date_from | string | no | 期間起始（YYYY-MM-DD）。 |
| date_to | string | no | 期間結束（YYYY-MM-DD）。 |
| limit | integer | no | 回傳筆數（預設 100，最大 5000）。 |
Response Shape#
回應為 canonical envelope payload，頂層包含 api_version/endpoint/request_id/plan_id/dataset/query/meta/envelope。
實際資料列位於 `envelope.data[]`，非 productized endpoint 的 `rows`。
{
"api_version": "v2",
"endpoint": "/v2/datasets/financials",
"request_id": "req_abc123def456",
"plan_id": "free",
"dataset": "financials",
"query": {
"ticker": "2330",
"statement_type": "income_statement",
"period_type": "quarterly",
"date_from": "2025-01-01",
"date_to": "2026-12-31",
"limit": 5
},
"meta": {
"rows_returned": 1,
"mandatory_contract_fields_present": [
"api_version",
"dataset",
"dataset_version",
"release_date",
"release_version",
"request_context",
"data",
"quality",
"lineage",
"error"
]
},
"envelope": {
"api_version": "v2",
"dataset": "financials",
"dataset_version": "v2.0.0-preview",
"release_version": "v2.2026-04-23.preview",
"release_date": "2026-04-23",
"request_context": {
"ticker": "2330",
"as_of_date": "2026-12-31",
"family": "fundamentals",
"field_group_type": "fundamental_statement",
"dataset_view": "fundamental_statements_v1"
},
"data": [
{
"ticker": "2330",
"statement_type": "income_statement",
"period_type": "quarterly",
"fiscal_period_end": "2025-12-31",
"report_date": "2026-03-08",
"fiscal_year": 2025,
"fiscal_quarter": 4,
"currency": "TWD",
"source_id": "mops_official",
"fields": {
"revenue": 625000000000,
"gross_profit": 320000000000,
"operating_income": 250000000000,
"pretax_income": 246000000000,
"net_income": 210000000000,
"eps": 8.1
},
"quality_flag": "ok"
}
],
"quality": {
"freshness_state": "fresh",
"freshness_as_of": "2026-12-31",
"completeness_ratio": 1,
"quality_status": "ready"
},
"lineage": {
"source_role": "canonical",
"selected_source": "mops_official",
"fallback_chain": [
"data_gov_mirror",
"finmind_legacy"
],
"policy_notes": [
"official/public-first canonical"
]
},
"error": {
"error_code": null,
"error_message": null,
"dataset": "financials",
"request_id": "read-api-abc123def456",
"blocking_gate": null
}
}
}Field 說明#
| 欄位路徑 | 型別 | 說明 |
|---|---|---|
| dataset | string | 固定為 financials。 |
| query.ticker | string|null | 查詢 ticker。 |
| query.statement_type | string|null | 查詢財報類型。 |
| meta.rows_returned | integer | 回傳資料列數。 |
| envelope.data[].ticker | string | 股票代碼。 |
| envelope.data[].statement_type | string | 財報類型。 |
| envelope.data[].period_type | string | 期間類型。 |
| envelope.data[].fields | object | 對應 statement 的欄位集合。 |
| envelope.quality.quality_status | string | 資料品質狀態。 |
| envelope.lineage.source_role | string | 來源角色（canonical/fallback/helper/legacy）。 |
Usage Notes / 使用建議#
- 此頁為 canonical/supplemental surface，非主產品 endpoint。
- 主公開對外建議：`/v2/datasets/income-statement`（symbol + dataset/rows/count）。
- canonical endpoint 使用 `ticker` 參數，請勿視為主 endpoint 的替代叫法。
Plan Requirement#
- Free（限制）
- Developer
- Pro
- Enterprise