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

查詢與工具

查詢 API

提供 allowlist 欄位查詢能力，適合固定契約資料提取與 explainability 驗證。

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

GET/v2/query

Overview

查詢 API 提供嚴格 allowlist 的欄位查詢能力，適合在固定契約下擷取跨資料主題欄位。

回應預設附帶 explainability metadata，可直接用於來源驗證與欄位審計。

以單一 issuer/index 抽取固定欄位，供策略與面板使用。
批次查詢多標的並取得共享 explainability metadata。
搭配 `/v2/query/fields` 先查 allowlist，再動態組裝查詢。

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

必填條件為 `entity_type`、`fields`，且必須提供 `entity_id` 或 `entity_ids[]` 其中之一。單次最多 10 個 entity。

Query Parameters

欄位	型別	Required	說明
entity_id	string	no	單一實體識別（ticker 或 index code）。
entity_ids	string	no	逗號分隔的批次實體識別。
entity_ids[]	string[]	no	重複 query 參數的批次實體識別。
entity_type	string	yes	issuer 或 index。
fields	string	yes	逗號分隔欄位清單。
fields[]	string[]	no	重複 query 參數欄位清單。
as_of_date	string	no	查詢基準日（YYYY-MM-DD）。
minimal_fields	boolean	no	true 時省略 explainability payload。

Response Shape

單筆模式回傳 `data + explainability`；批次模式回傳 `results + explainability_shared`。

dataset 固定為 `field_query`，不支援任意 SQL passthrough。

{  "api_version": "v2",  "endpoint": "/v2/query",  "request_id": "req_query_4e6a8c0d",  "plan_id": "developer",  "dataset": "field_query",  "entity_id": "2330",  "entity_type": "issuer",  "as_of_date": "2026-04-22",  "fields": [    "company_name",    "pe_ratio",    "revenue_yoy_pct"  ],  "data": {    "company_name": "台灣積體電路製造股份有限公司",    "pe_ratio": 26.8,    "revenue_yoy_pct": 0.18  },  "explainability": {    "company_name": {      "source_topic": "issuer_profile",      "source_table_or_contract": "issuer_profiles",      "source_field": "company_name",      "attach_rule": "exact_entity_attach",      "formula": null,      "nullability_rule": "nullable_if_source_missing",      "freshness_basis": "latest_on_or_before(as_of_date)"    }  },  "errors": [],  "meta": {    "batch_mode": false,    "supported_entity_types": [      "index",      "issuer"    ]  }}

Field 說明

欄位路徑	型別	說明
dataset	string	固定為 field_query。
entity_type	string	issuer 或 index。
fields[]	string[]	實際解析後欄位清單。
data	object	單筆模式欄位值映射。
results[]	array	批次模式結果列。
explainability	object	單筆模式欄位級解釋資訊。
explainability_shared	object	批次模式共享 explainability 區塊。
errors[]	array	欄位或請求錯誤資訊。
meta.allowlist	array	目前 entity_type 可用欄位列表。

Usage Notes / 使用建議

Companion endpoints：`/v2/query/fields`（欄位契約）與 `/v2/query/examples`（請求範例）。
unsupported_field 會明確出現在 errors，不會默默忽略。
Explainability 為 deterministic 映射，不包含 LLM 生成敘述。

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

Routes：/v2/query、/v2/query/fields、/v2/query/examples
實際可用範圍與配額以控制台方案顯示為準

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

請求與回應

Request example

curl --request GET \  --url "https://api.twmarketdata.com/v2/query?entity_id=2330&entity_type=issuer&fields=company_name,pe_ratio,revenue_yoy_pct&as_of_date=2026-04-22" \  --header "X-API-Key: your_api_key_here"

Status codes

成功回傳欄位查詢結果

JSON

{  "api_version": "v2",  "endpoint": "/v2/query",  "request_id": "req_query_4e6a8c0d",  "plan_id": "developer",  "dataset": "field_query",  "entity_id": "2330",  "entity_type": "issuer",  "as_of_date": "2026-04-22",  "fields": [    "company_name",    "pe_ratio",    "revenue_yoy_pct"  ],  "data": {    "company_name": "台灣積體電路製造股份有限公司",    "pe_ratio": 26.8,    "revenue_yoy_pct": 0.18  },  "explainability": {    "company_name": {      "source_topic": "issuer_profile",      "source_table_or_contract": "issuer_profiles",      "source_field": "company_name",      "attach_rule": "exact_entity_attach",      "formula": null,      "nullability_rule": "nullable_if_source_missing",      "freshness_basis": "latest_on_or_before(as_of_date)"    }  },  "errors": [],  "meta": {    "batch_mode": false,    "supported_entity_types": [      "index",      "issuer"    ]  }}