條件篩選

搜尋

Overview#

提供條件式篩選能力，快速縮小標的範圍。

此 endpoint 提供穩定的契約格式，可直接整合至資料管線、回測系統與自動化流程。

Request#

此 endpoint 常見使用情境：

• 研究篩選、候選池建立與策略前置選股
• 建立單一來源的資料查詢層，降低跨來源整合成本。
• 在研究與生產環境共用同一組 request / response 契約。

建議接入步驟：

1. 1. 在 header 放入 X-API-Key。
2. 2. 先以單一 ticker 或小範圍條件驗證回應格式。
3. 3. 確認欄位後再擴展至批次查詢與分頁流程。

curl -X GET "https://api.twmarketdata.com/v2/search/screening?limit=10" \
  -H "X-API-Key: your_api_key_here"

Response#

回應採統一 envelope，固定包含 dataset、source_role、freshness、lineage、data。

data 欄位會依 endpoint 性質回傳陣列或單一物件，但欄位命名與型別維持穩定。

{
  "dataset": "filter_screening",
  "source_role": "canonical",
  "freshness": "2026-04-21T10:30:00+08:00",
  "lineage": {
    "source": "平台索引",
    "ingested_at": "2026-04-21T10:30:02+08:00",
    "trace_id": "filter_screening_2330_20260421"
  },
  "data": [
    {
      "ticker": "2308",
      "name": "台達電",
      "pe": 22.1,
      "market_cap": 1004200000000
    },
    {
      "ticker": "2454",
      "name": "聯發科",
      "pe": 18.7,
      "market_cap": 1883300000000
    }
  ]
}

Field 說明#

使用建議#

• 建議使用 ticker 作為 join key，避免以名稱匹配造成錯配。
• 批次查詢請使用 limit / offset，避免單次大量請求超出 rate limit。
• 整合多 endpoint 時，請保留 source_role 與 lineage 以便驗證與排錯。