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

查詢與工具

搜尋 API

提供 deterministic 實體搜尋能力，支援 issuer、index、theme 三類查找。

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

GET/v2/search

Overview

搜尋 API 提供 deterministic 的實體搜尋能力，可在 issuer/index/theme 三種實體之間統一查找。

這是對外公開能力，路徑為 `/v2/search`，不使用向量檢索或 LLM 排名。

輸入公司名稱或代碼，快速定位 ticker。
在 index/theme 維度快速找可用實體。
作為 query 前置步驟，先定位 entity 再提取欄位。

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

必填參數為 `q`；`type` 可選 `issuer | index | theme | all`。若 type 不支援，會回傳 `unsupported_search_type`。

Query Parameters

欄位	型別	Required	說明
q	string	yes	搜尋字串。
type	string	no	issuer \| index \| theme \| all（預設 all）。
limit	integer	no	回傳筆數限制（1..100）。
offset	integer	no	分頁偏移（>=0）。

Response Shape

回應固定包含 `dataset=universal_search`、`query`、`meta`、`results`、`errors`。

空結果以 200 + results=[] 回傳，不以 404 表示。

{  "api_version": "v2",  "endpoint": "/v2/search",  "request_id": "req_search_5b7d9f1a",  "plan_id": "developer",  "dataset": "universal_search",  "query": {    "q": "台積電",    "type": "issuer",    "limit": 20,    "offset": 0  },  "meta": {    "rows_returned": 1,    "supported_types": [      "all",      "index",      "issuer",      "theme"    ]  },  "results": [    {      "entity_type": "issuer",      "ticker": "2330",      "market": "TWSE",      "company_name": "台灣積體電路製造股份有限公司",      "english_name": "Taiwan Semiconductor Manufacturing Co., Ltd.",      "matched_on": "company_name_contains",      "provider": "twse_official",      "source_role": "canonical"    }  ],  "errors": []}

Field 說明

欄位路徑	型別	說明
dataset	string	固定為 universal_search。
query	object	本次查詢參數回填。
meta.rows_returned	integer	回傳筆數。
results[].entity_type	string	實體類型（issuer/index/theme）。
results[].ticker	string\|null	股票代碼（issuer 時常見）。
results[].index_code	string\|null	指數代碼（index 時常見）。
results[].theme_primary	string\|null	主題欄位（theme 時常見）。
results[].matched_on	string	命中欄位/規則。
results[].source_role	string\|null	來源角色。
results[].lineage	object\|string\|null	來源追溯資訊。
errors[]	array	錯誤欄位（分支失敗或參數問題）。

Usage Notes / 使用建議

排序策略是 deterministic 規則，不包含語意向量或模型 rerank。
如果某個分支來源表為空，系統會回 200 空結果而不是 500。
推薦流程：先 `/v2/search` 定位，再使用 `/v2/query` 擷取欄位。

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

Route：/v2/search
實際可用範圍與配額以控制台方案顯示為準

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

請求與回應

Request example

curl --request GET \  --url "https://api.twmarketdata.com/v2/search?q=%E5%8F%B0%E7%A9%8D%E9%9B%BB&type=issuer&limit=20" \  --header "X-API-Key: your_api_key_here"

Status codes

成功回傳搜尋結果

JSON

{  "api_version": "v2",  "endpoint": "/v2/search",  "request_id": "req_search_5b7d9f1a",  "plan_id": "developer",  "dataset": "universal_search",  "query": {    "q": "台積電",    "type": "issuer",    "limit": 20,    "offset": 0  },  "meta": {    "rows_returned": 1,    "supported_types": [      "all",      "index",      "issuer",      "theme"    ]  },  "results": [    {      "entity_type": "issuer",      "ticker": "2330",      "market": "TWSE",      "company_name": "台灣積體電路製造股份有限公司",      "english_name": "Taiwan Semiconductor Manufacturing Co., Ltd.",      "matched_on": "company_name_contains",      "provider": "twse_official",      "source_role": "canonical"    }  ],  "errors": []}

Overview

搜尋 API 提供 deterministic 的實體搜尋能力，可在 issuer/index/theme 三種實體之間統一查找。

這是對外公開能力，路徑為 `/v2/search`，不使用向量檢索或 LLM 排名。

輸入公司名稱或代碼，快速定位 ticker。

在 index/theme 維度快速找可用實體。

作為 query 前置步驟，先定位 entity 再提取欄位。

Instruments

Start year

Update timing

Includes delisted

Not yet available (coming)

coming

欄位

型別

Required

說明

string

yes

搜尋字串。

type

string

issuer | index | theme | all（預設 all）。

limit

integer

回傳筆數限制（1..100）。

offset

integer

分頁偏移（>=0）。

Response Shape

回應固定包含 `dataset=universal_search`、`query`、`meta`、`results`、`errors`。

空結果以 200 + results=[] 回傳，不以 404 表示。

{  "api_version": "v2",  "endpoint": "/v2/search",  "request_id": "req_search_5b7d9f1a",  "plan_id": "developer",  "dataset": "universal_search",  "query": {    "q": "台積電",    "type": "issuer",    "limit": 20,    "offset": 0  },  "meta": {    "rows_returned": 1,    "supported_types": [      "all",      "index",      "issuer",      "theme"    ]  },  "results": [    {      "entity_type": "issuer",      "ticker": "2330",      "market": "TWSE",      "company_name": "台灣積體電路製造股份有限公司",      "english_name": "Taiwan Semiconductor Manufacturing Co., Ltd.",      "matched_on": "company_name_contains",      "provider": "twse_official",      "source_role": "canonical"    }  ],  "errors": []}

Field 說明

欄位路徑	型別	說明
dataset	string	固定為 universal_search。
query	object	本次查詢參數回填。
meta.rows_returned	integer	回傳筆數。
results[].entity_type	string	實體類型（issuer/index/theme）。
results[].ticker	string\|null	股票代碼（issuer 時常見）。
results[].index_code	string\|null	指數代碼（index 時常見）。
results[].theme_primary	string\|null	主題欄位（theme 時常見）。
results[].matched_on	string	命中欄位/規則。
results[].source_role	string\|null	來源角色。
results[].lineage	object\|string\|null	來源追溯資訊。
errors[]	array	錯誤欄位（分支失敗或參數問題）。

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.

{ "api_version": "v2", "endpoint": "/v2/search", "request_id": "req_search_5b7d9f1a", "plan_id": "developer", "dataset": "universal_search", "query": { "q": "台積電", "type": "issuer", "limit": 20, "offset": 0 }, "meta": { "rows_returned": 1, "supported_types": [ "all", "index", "issuer", "theme" ] }, "results": [ { "entity_type": "issuer", "ticker": "2330", "market": "TWSE", "company_name": "台灣積體電路製造股份有限公司", "english_name": "Taiwan Semiconductor Manufacturing Co., Ltd.", "matched_on": "company_name_contains", "provider": "twse_official", "source_role": "canonical" } ], "errors": []}