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

財務與成長（Canonical）

財報資料（Canonical）

canonical/supplemental 財報查詢面，適用於低階契約與資料對齊流程。

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

GET/v2/datasets/financials

Overview

financials 是 canonical/supplemental surface，提供較低階、可組合的財報結構資料。

此 route 不是主公開產品頁；若要穩定對外整合，優先使用 `/v2/datasets/income-statement`。

需要 statement_type（income/balance/cash flow）共用查詢入口時。
內部或進階流程需直接讀 canonical envelope 時。
做欄位映射或 schema 對照測試時。

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 時，請注意它與 productized endpoint 契約不同。

Query Parameters

欄位	型別	Required	說明
symbol	string	no	股票代碼（例如 2330）。
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 的替代叫法。

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/financials?symbol=2330&statement_type=income_statement&period_type=quarterly&date_from=2025-01-01&date_to=2026-12-31&limit=5" \  --header "X-API-Key: your_api_key_here"

Status codes

成功回傳 canonical financials payload

JSON

{  "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    }  }}