查詢與工具
搜尋 API
提供 deterministic 實體搜尋能力，支援 issuer、index、theme 三類查找。
GET
/v2/searchOverview#
搜尋 API 提供 deterministic 的實體搜尋能力，可在 issuer/index/theme 三種實體之間統一查找。
這是對外公開能力，路徑為 `/v2/search`，不使用向量檢索或 LLM 排名。
- 輸入公司名稱或代碼，快速定位 ticker。
- 在 index/theme 維度快速找可用實體。
- 作為 query 前置步驟，先定位 entity 再提取欄位。
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` 擷取欄位。
Plan / Readiness#
- Status：productized capability（registry: universal_search）
- Route：/v2/search
- 實際 entitlement 以 API key 方案與 rate/quota 設定為準