{ "openapi": "3.1.0", "info": { "title": "TW Market Data API", "description": "台股資料 API，為 AI agent、量化研究與金融產品開發設計。此文件提供 machine-readable 的公開資料端點摘要，詳細欄位請以對應 docs endpoint 頁面為準。", "version": "0.1.0" }, "servers": [ { "url": "https://twmarketdata.com" } ], "security": [ { "ApiKeyAuth": [] } ], "paths": { "/v2/datasets/twse-daily-price": { "get": { "summary": "TWSE 日線價格 / TWSE daily prices", "description": "上市股票日線價格資料，適合價格走勢、回測與技術指標輸入。", "parameters": [ { "$ref": "#/components/parameters/TickerParam" }, { "$ref": "#/components/parameters/StartDateParam" }, { "$ref": "#/components/parameters/EndDateParam" }, { "$ref": "#/components/parameters/LimitParam" } ], "responses": { "200": { "description": "TWSE daily price rows returned successfully.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/DatasetResponseEnvelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/TwseDailyPriceRow" } } } } ] }, "examples": { "standard": { "value": { "data": [ { "ticker": "2330", "market": "TWSE", "trade_date": "2026-04-30", "open": 812, "high": 818, "low": 805, "close": 810, "volume": 21500000, "turnover": 17415000000, "provider": "twse", "source_role": "official_twse_daily_price" } ], "meta": { "dataset": "twse-daily-price", "request_id": "req_twse_001", "generated_at": "2026-05-23T00:00:00Z", "ticker": "2330", "market": "TWSE", "date_from": "2026-04-01", "date_to": "2026-04-30", "source_policy": "official/public-first", "freshness": "daily-close", "currency": "TWD", "unit_semantics": "shares" }, "pagination": { "limit": 50, "next_cursor": null, "has_more": false }, "data_gaps": [] } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "x-data-status": "production", "x-data-gaps": "Response may include data_gaps and coverage/freshness caveats.", "operationId": "getTwseDailyPrice", "tags": [ "Market Prices" ], "externalDocs": { "description": "對應 API 文件", "url": "https://twmarketdata.com/docs/api/market-prices/twse-daily-price" }, "x-source-policy": "official/public-first with explicit lineage and data_gaps.", "x-coverage-note": "TWSE daily price is a core dataset, but availability can still vary by date/ticker and ingestion state.", "x-data-gaps-policy": "Preserve and surface data_gaps; do not auto-fill missing observations.", "x-dataset-page": "https://twmarketdata.com/datasets/twse-daily-price", "x-docs-page": "https://twmarketdata.com/docs/api/market-prices/twse-daily-price", "x-freshness-note": "Daily close oriented dataset; verify freshness fields before downstream decisions.", "x-stability": "stable" } }, "/v2/datasets/tpex-daily-price": { "get": { "summary": "TPEx 日線價格 / TPEx daily prices", "description": "上櫃股票日線價格與成交資訊。", "parameters": [ { "$ref": "#/components/parameters/Symbol" }, { "$ref": "#/components/parameters/StartDate" }, { "$ref": "#/components/parameters/EndDate" }, { "$ref": "#/components/parameters/Limit" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DatasetResponseEnvelope" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate Limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-data-status": "production", "x-data-gaps": "Response may include data_gaps and coverage/freshness caveats." } }, "/v2/datasets/monthly-revenue": { "get": { "summary": "月營收 / Monthly revenue", "description": "公司月營收資料，可用於成長追蹤與基本面研究流程。", "parameters": [ { "$ref": "#/components/parameters/TickerParam" }, { "$ref": "#/components/parameters/StartDateParam" }, { "$ref": "#/components/parameters/EndDateParam" }, { "$ref": "#/components/parameters/LimitParam" } ], "responses": { "200": { "description": "Monthly revenue rows returned successfully.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/DatasetResponseEnvelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/MonthlyRevenueRow" } } } } ] }, "examples": { "standard": { "value": { "data": [ { "ticker": "2330", "revenue_month": "2026-03", "revenue": 249800000000, "revenue_yoy": 0.182, "revenue_mom": 0.031, "provider": "twse", "source_role": "official_monthly_revenue" } ], "meta": { "dataset": "monthly-revenue", "request_id": "req_mrev_001", "generated_at": "2026-05-23T00:00:00Z", "ticker": "2330", "market": "TWSE", "date_from": "2026-01-01", "date_to": "2026-03-31", "source_policy": "official/public-first", "freshness": "monthly-disclosure", "currency": "TWD", "unit_semantics": "currency" }, "pagination": { "limit": 24, "next_cursor": null, "has_more": false }, "data_gaps": [ { "code": "disclosure_lag", "message": "最新月份尚在官方揭露窗口內。", "severity": "warning", "scope": "dataset", "field": "revenue_month", "source": "official disclosure cadence", "observed_at": "2026-05-23T00:00:00Z" } ] } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "x-data-status": "production", "x-data-gaps": "Response may include data_gaps and coverage/freshness caveats.", "operationId": "getMonthlyRevenue", "tags": [ "Fundamentals" ], "externalDocs": { "description": "對應 API 文件", "url": "https://twmarketdata.com/docs/api/financial-growth/monthly-revenue" }, "x-source-policy": "official/public-first with explicit lineage and data_gaps.", "x-coverage-note": "Coverage depends on official filing availability and normalization progress.", "x-data-gaps-policy": "Preserve disclosure-lag and missing-period gaps as explicit data_gaps entries.", "x-dataset-page": "https://twmarketdata.com/datasets/monthly-revenue", "x-docs-page": "https://twmarketdata.com/docs/api/financial-growth/monthly-revenue", "x-freshness-note": "Monthly disclosure cadence applies; check freshness before cross-dataset joins.", "x-stability": "stable" } }, "/v2/datasets/income-statement": { "get": { "summary": "損益表 / Income statement", "description": "季度損益表資料，支援獲利能力與估值基礎分析。", "parameters": [ { "$ref": "#/components/parameters/TickerParam" }, { "$ref": "#/components/parameters/StartDateParam" }, { "$ref": "#/components/parameters/EndDateParam" }, { "$ref": "#/components/parameters/LimitParam" } ], "responses": { "200": { "description": "Income statement rows returned successfully.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/DatasetResponseEnvelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/IncomeStatementRow" } } } } ] }, "examples": { "standard": { "value": { "data": [ { "ticker": "2330", "fiscal_year": 2025, "fiscal_quarter": 4, "revenue": 798400000000, "gross_profit": 422100000000, "operating_income": 359600000000, "net_income": 312200000000, "eps": 12.03, "provider": "twse", "source_role": "official_income_statement" } ], "meta": { "dataset": "income-statement", "request_id": "req_is_001", "generated_at": "2026-05-23T00:00:00Z", "ticker": "2330", "market": "TWSE", "date_from": "2025-01-01", "date_to": "2025-12-31", "source_policy": "official/public-first", "freshness": "quarterly-filing", "currency": "TWD", "unit_semantics": "currency" }, "pagination": { "limit": 12, "next_cursor": null, "has_more": false }, "data_gaps": [ { "code": "filing_lag", "message": "最新季度尚未完成公告。", "severity": "info", "scope": "quarter", "field": "fiscal_quarter", "source": "official filing schedule", "observed_at": "2026-05-23T00:00:00Z" } ] } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "x-data-status": "production", "x-data-gaps": "Response may include data_gaps and coverage/freshness caveats.", "operationId": "getIncomeStatement", "tags": [ "Fundamentals" ], "externalDocs": { "description": "對應 API 文件", "url": "https://twmarketdata.com/docs/api/financial-growth/income-statement" }, "x-source-policy": "official/public-first with explicit lineage and data_gaps.", "x-coverage-note": "Quarterly coverage can vary by filing schedule and source readiness.", "x-data-gaps-policy": "Expose filing-period gaps explicitly; do not infer absent quarterly filings.", "x-dataset-page": "https://twmarketdata.com/datasets/income-statement", "x-docs-page": "https://twmarketdata.com/docs/api/financial-growth/income-statement", "x-freshness-note": "Quarterly filing lag applies; verify latest available fiscal period.", "x-stability": "stable" } }, "/v2/datasets/balance-sheet": { "get": { "summary": "資產負債表 / Balance sheet", "description": "季度資產負債表資料，用於財務結構與風險承受力分析。", "parameters": [ { "$ref": "#/components/parameters/TickerParam" }, { "$ref": "#/components/parameters/StartDateParam" }, { "$ref": "#/components/parameters/EndDateParam" }, { "$ref": "#/components/parameters/LimitParam" } ], "responses": { "200": { "description": "Balance sheet rows returned successfully.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/DatasetResponseEnvelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/BalanceSheetRow" } } } } ] }, "examples": { "standard": { "value": { "data": [ { "ticker": "2330", "fiscal_year": 2025, "fiscal_quarter": 4, "total_assets": 5798000000000, "total_liabilities": 2134000000000, "equity": 3664000000000, "cash_and_cash_equivalents": 1643000000000, "provider": "twse", "source_role": "official_balance_sheet" } ], "meta": { "dataset": "balance-sheet", "request_id": "req_bs_001", "generated_at": "2026-05-23T00:00:00Z", "ticker": "2330", "market": "TWSE", "date_from": "2025-01-01", "date_to": "2025-12-31", "source_policy": "official/public-first", "freshness": "quarterly-filing", "currency": "TWD", "unit_semantics": "currency" }, "pagination": { "limit": 12, "next_cursor": null, "has_more": false }, "data_gaps": [ { "code": "filing_lag", "message": "部分最新季度欄位尚未揭露。", "severity": "warning", "scope": "quarter", "field": null, "source": "official filing schedule", "observed_at": "2026-05-23T00:00:00Z" } ] } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "x-data-status": "production", "x-data-gaps": "Response may include data_gaps and coverage/freshness caveats.", "operationId": "getBalanceSheet", "tags": [ "Fundamentals" ], "externalDocs": { "description": "對應 API 文件", "url": "https://twmarketdata.com/docs/api/financial-growth/balance-sheet" }, "x-source-policy": "official/public-first with explicit lineage and data_gaps.", "x-coverage-note": "Coverage is tied to quarterly filing availability and normalization status.", "x-data-gaps-policy": "Retain missing-quarter and field-level gaps with explicit diagnostics.", "x-dataset-page": "https://twmarketdata.com/datasets/balance-sheet", "x-docs-page": "https://twmarketdata.com/docs/api/financial-growth/balance-sheet", "x-freshness-note": "Quarterly filing lag applies; validate period availability before use.", "x-stability": "stable" } }, "/v2/datasets/institutional-flow": { "get": { "summary": "三大法人買賣超 / Institutional flow", "description": "三大法人買賣超資料，用於籌碼與資金流向分析。", "parameters": [ { "$ref": "#/components/parameters/TickerParam" }, { "$ref": "#/components/parameters/StartDateParam" }, { "$ref": "#/components/parameters/EndDateParam" }, { "$ref": "#/components/parameters/LimitParam" } ], "responses": { "200": { "description": "Institutional flow rows returned successfully.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/DatasetResponseEnvelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/InstitutionalFlowRow" } } } } ] }, "examples": { "standard": { "value": { "data": [ { "ticker": "2330", "market": "TWSE", "trade_date": "2026-04-30", "foreign_net_buy": 1250000, "investment_trust_net_buy": -82000, "dealer_net_buy": 43000, "institutional_net_buy_total": 1211000, "unit_semantics": "shares", "provider": "twse", "source_role": "official_twse_t86" } ], "meta": { "dataset": "institutional-flow", "request_id": "req_flow_001", "generated_at": "2026-05-23T00:00:00Z", "ticker": "2330", "market": "TWSE", "date_from": "2026-04-01", "date_to": "2026-04-30", "source_policy": "official/public-first", "freshness": "daily", "currency": null, "unit_semantics": "shares" }, "pagination": { "limit": 50, "next_cursor": null, "has_more": false }, "data_gaps": [ { "code": "coverage_rollout_gap", "message": "部分標的或日期仍在 coverage 補齊中。", "severity": "warning", "scope": "dataset", "field": null, "source": "official source rollout", "observed_at": "2026-05-23T00:00:00Z" } ] } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "x-data-status": "coverage-limited", "x-data-gaps": "Response may include data_gaps and coverage/freshness caveats.", "operationId": "getInstitutionalFlow", "tags": [ "Capital Flow" ], "externalDocs": { "description": "對應 API 文件", "url": "https://twmarketdata.com/docs/api/capital-flow/institutional-flow" }, "x-source-policy": "official/public-first with explicit lineage and data_gaps.", "x-coverage-note": "Coverage is being expanded and may be limited for some dates/tickers.", "x-data-gaps-policy": "Keep coverage rollout gaps explicit; do not substitute missing flow with zeros.", "x-dataset-page": "https://twmarketdata.com/datasets/institutional-flow", "x-docs-page": "https://twmarketdata.com/docs/api/capital-flow/institutional-flow", "x-freshness-note": "Daily update cadence varies by source availability; check freshness and data_gaps.", "x-stability": "coverage_limited" } }, "/v2/datasets/technical-indicators": { "get": { "summary": "技術指標 / Technical indicators", "description": "由價格資料衍生的技術分析指標。", "parameters": [ { "$ref": "#/components/parameters/Symbol" }, { "$ref": "#/components/parameters/StartDate" }, { "$ref": "#/components/parameters/EndDate" }, { "$ref": "#/components/parameters/Limit" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DatasetResponseEnvelope" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate Limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-data-status": "production", "x-data-gaps": "Response may include data_gaps and coverage/freshness caveats." } }, "/v2/datasets/valuation-data": { "get": { "summary": "估值資料 / Valuation data", "description": "本益比、股價淨值比、殖利率等估值欄位。", "parameters": [ { "$ref": "#/components/parameters/Symbol" }, { "$ref": "#/components/parameters/StartDate" }, { "$ref": "#/components/parameters/EndDate" }, { "$ref": "#/components/parameters/Limit" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DatasetResponseEnvelope" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate Limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-data-status": "production", "x-data-gaps": "Response may include data_gaps and coverage/freshness caveats." } }, "/v2/datasets/issuer-profile": { "get": { "summary": "公司基本資料 / Issuer profile", "description": "公司識別、上市櫃別與產業分類等基本資訊。", "parameters": [ { "$ref": "#/components/parameters/Symbol" }, { "$ref": "#/components/parameters/Limit" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DatasetResponseEnvelope" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate Limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-data-status": "production", "x-data-gaps": "Response may include data_gaps and coverage/freshness caveats." } } }, "components": { "parameters": { "Symbol": { "name": "symbol", "in": "query", "required": false, "schema": { "type": "string" }, "description": "股票代號，例如 2330。" }, "StartDate": { "name": "start_date", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "查詢起始日期（YYYY-MM-DD）。" }, "EndDate": { "name": "end_date", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "查詢結束日期（YYYY-MM-DD）。" }, "Limit": { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 500 }, "description": "回傳筆數上限。" }, "TickerParam": { "name": "symbol", "in": "query", "required": true, "schema": { "type": "string" }, "description": "股票代碼（對應 ticker），例如 2330。" }, "StartDateParam": { "name": "start_date", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "查詢起始日期（YYYY-MM-DD）。" }, "EndDateParam": { "name": "end_date", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "查詢結束日期（YYYY-MM-DD）。" }, "LimitParam": { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 1000 }, "description": "回傳筆數上限。" } }, "securitySchemes": { "ApiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "Use X-API-Key header with your dashboard-issued API key." } }, "schemas": { "DatasetResponseEnvelope": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "meta": { "$ref": "#/components/schemas/DatasetMeta" }, "pagination": { "$ref": "#/components/schemas/PaginationMeta" }, "data_gaps": { "type": "array", "items": { "$ref": "#/components/schemas/DataGap" } } }, "example": { "data": [], "meta": { "dataset": "twse-daily-price", "request_id": "req_example_001", "generated_at": "2026-05-23T00:00:00Z", "ticker": "2330", "market": "TWSE", "date_from": "2026-01-01", "date_to": "2026-01-31", "source_policy": "official/public-first", "freshness": "daily-close", "currency": "TWD", "unit_semantics": "shares" }, "pagination": { "limit": 50, "next_cursor": null, "has_more": false }, "data_gaps": [] } }, "DataGap": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "severity": { "type": "string", "enum": [ "info", "warning", "error" ] }, "scope": { "type": [ "string", "null" ] }, "field": { "type": [ "string", "null" ] }, "source": { "type": [ "string", "null" ] }, "observed_at": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true, "example": { "code": "coverage_rollout_gap", "message": "部分日期尚未完成來源補齊。", "severity": "warning", "scope": "dataset", "field": null, "source": "official source rollout", "observed_at": "2026-05-23T00:00:00Z" } }, "PaginationMeta": { "type": "object", "properties": { "limit": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 1000 }, "next_cursor": { "type": [ "string", "null" ] }, "has_more": { "type": [ "boolean", "null" ] } }, "example": { "limit": 50, "next_cursor": null, "has_more": false }, "additionalProperties": true }, "ErrorResponse": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": [ "string", "null" ] } }, "additionalProperties": true } }, "examples": { "invalid_query": { "value": { "error": { "code": "INVALID_QUERY", "message": "查詢參數格式錯誤。", "request_id": "req_invalid_001" } } }, "unauthorized": { "value": { "error": { "code": "UNAUTHORIZED", "message": "缺少或無效的 API key。", "request_id": "req_auth_001" } } }, "rate_limited": { "value": { "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "請求過於頻繁，請稍後重試。", "request_id": "req_rate_001" } } }, "internal_error": { "value": { "error": { "code": "INTERNAL_ERROR", "message": "伺服器暫時無法處理請求。", "request_id": "req_internal_001" } } } } }, "SourceLineage": { "type": "object", "properties": { "provider": { "type": [ "string", "null" ], "description": "資料提供方代碼，例如 twse、tpex。" }, "source_role": { "type": [ "string", "null" ], "description": "來源角色，如 canonical/fallback/helper。" }, "source_name": { "type": [ "string", "null" ], "description": "來源名稱或來源主題。" }, "unit_semantics": { "type": [ "string", "null" ], "description": "數值單位語義，例如 shares、TWD。" }, "last_updated_at": { "type": [ "string", "null" ], "format": "date-time", "description": "來源層最近更新時間（若可用）。" } }, "additionalProperties": true }, "DatasetMeta": { "type": "object", "properties": { "dataset": { "type": [ "string", "null" ] }, "request_id": { "type": [ "string", "null" ] }, "generated_at": { "type": [ "string", "null" ], "format": "date-time" }, "ticker": { "type": [ "string", "null" ] }, "market": { "type": [ "string", "null" ] }, "date_from": { "type": [ "string", "null" ], "format": "date" }, "date_to": { "type": [ "string", "null" ], "format": "date" }, "source_policy": { "type": [ "string", "null" ] }, "freshness": { "type": [ "string", "null" ] }, "currency": { "type": [ "string", "null" ] }, "unit_semantics": { "type": [ "string", "null" ] } }, "additionalProperties": true }, "TwseDailyPriceRow": { "type": "object", "properties": { "ticker": { "type": "string" }, "market": { "type": [ "string", "null" ] }, "date": { "type": "string", "format": "date" }, "open": { "type": [ "number", "null" ] }, "high": { "type": [ "number", "null" ] }, "low": { "type": [ "number", "null" ] }, "close": { "type": [ "number", "null" ] }, "volume": { "type": [ "integer", "null" ] }, "provider": { "type": [ "string", "null" ] }, "source_role": { "type": [ "string", "null" ] } }, "additionalProperties": true }, "MonthlyRevenueRow": { "type": "object", "properties": { "ticker": { "type": "string" }, "revenue_month": { "type": [ "string", "null" ] }, "revenue": { "type": [ "number", "null" ] }, "revenue_yoy": { "type": [ "number", "null" ] }, "revenue_mom": { "type": [ "number", "null" ] }, "provider": { "type": [ "string", "null" ] }, "source_role": { "type": [ "string", "null" ] } }, "additionalProperties": true }, "IncomeStatementRow": { "type": "object", "properties": { "ticker": { "type": "string" }, "fiscal_period": { "type": [ "string", "null" ] }, "revenue": { "type": [ "number", "null" ] }, "gross_profit": { "type": [ "number", "null" ] }, "operating_income": { "type": [ "number", "null" ] }, "net_income": { "type": [ "number", "null" ] }, "eps": { "type": [ "number", "null" ] }, "provider": { "type": [ "string", "null" ] }, "source_role": { "type": [ "string", "null" ] } }, "additionalProperties": true }, "BalanceSheetRow": { "type": "object", "properties": { "ticker": { "type": "string" }, "fiscal_period": { "type": [ "string", "null" ] }, "total_assets": { "type": [ "number", "null" ] }, "total_liabilities": { "type": [ "number", "null" ] }, "equity": { "type": [ "number", "null" ] }, "cash_and_cash_equivalents": { "type": [ "number", "null" ] }, "provider": { "type": [ "string", "null" ] }, "source_role": { "type": [ "string", "null" ] } }, "additionalProperties": true }, "InstitutionalFlowRow": { "type": "object", "properties": { "ticker": { "type": "string" }, "market": { "type": [ "string", "null" ] }, "date": { "type": "string", "format": "date" }, "foreign_net_buy": { "type": [ "number", "null" ] }, "investment_trust_net_buy": { "type": [ "number", "null" ] }, "dealer_net_buy": { "type": [ "number", "null" ] }, "institutional_net_buy_total": { "type": [ "number", "null" ] }, "unit_semantics": { "type": [ "string", "null" ], "description": "Typically shares." }, "provider": { "type": [ "string", "null" ] }, "source_role": { "type": [ "string", "null" ] } }, "additionalProperties": true } }, "responses": { "BadRequest": { "description": "Invalid query parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "invalid_query": { "value": { "error": { "code": "INVALID_QUERY", "message": "查詢參數格式錯誤。", "request_id": "req_invalid_001" } } } } } } }, "Unauthorized": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "unauthorized": { "value": { "error": { "code": "UNAUTHORIZED", "message": "缺少或無效的 API key。", "request_id": "req_auth_001" } } } } } } }, "TooManyRequests": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "rate_limited": { "value": { "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "請求過於頻繁，請稍後重試。", "request_id": "req_rate_001" } } } } } } }, "InternalServerError": { "description": "Unexpected server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "internal_error": { "value": { "error": { "code": "INTERNAL_ERROR", "message": "伺服器暫時無法處理請求。", "request_id": "req_internal_001" } } } } } } } } } }