Staging API · HTTPS enabled · Not production

Reality Intelligence API

台灣現實世界搜尋引擎 Taiwan World Model 的機器介面。這個 staging API 讓 TrueSight / Codex / internal tools 查詢目前可介接的現實資料能力，並測試 Reality Check 合約。

https://taiwanworldmodel.thesense.biz

目前狀態

• status=catalog_only：資料源能力目錄已可查詢。
• status=insufficient_data：Reality Check endpoint 可呼叫，但尚未接入正式即時資料源。
• 目前不是 production API；API clients、rate limit、audit log 仍是 in-memory。

Endpoints

查詢資料源能力

curl -s https://taiwanworldmodel.thesense.biz/v1/reality/sources   -H "X-API-Key: $TRUESIGHT_REALITY_API_KEY"

依 intent 過濾：

curl -s "https://taiwanworldmodel.thesense.biz/v1/reality/sources?intent=traffic_congestion"   -H "X-API-Key: $TRUESIGHT_REALITY_API_KEY"

送出 Reality Check

curl -s -X POST https://taiwanworldmodel.thesense.biz/v1/reality/check   -H "Content-Type: application/json"   -H "X-API-Key: $TRUESIGHT_REALITY_API_KEY"   -d '{"query":"阿里山現在有雲海嗎？"}'

Weather Reality API Usage：TrueSight 氣象查詢

TrueSight 目前可以先用 Reality API 查氣象資訊，暫時不啟用攝影機驗證。支援的 weather runtime intents 包含 rain_now、weather_suitability、flooding_risk。

curl -s -X POST https://taiwanworldmodel.thesense.biz/v1/reality/check   -H "Content-Type: application/json"   -H "X-API-Key: $TRUESIGHT_REALITY_API_KEY"   -d '{"query":"阿里山現在有下雨嗎？"}'

{
  "intent": "rain_now",
  "status": "configuration_required",
  "current_state": "unknown",
  "data_sources": ["cwa_weather_observation", "cwa_rainfall_observation"],
  "signals": [],
  "limitations": ["需要在服務環境設定 CWA_API_KEY"]
}

攝影機驗證下一階段：氣象 live data 穩定後，下一個大項目是公共攝影機白名單與 visual evidence，用來驗證氣象局實時資訊是否符合現場畫面。

Temperature Definitions：溫度定義

Weather Reality 會明確區分 室外實測氣溫 與 體感溫度，避免把測站溫度誤解為人體實際感受。

Reality Graph 資料源原則

Taiwan World Model 不是 CCTV 聚合器。官方資料是現實證據的一等公民；攝影機是眼睛，不是整個世界模型。

公共資源 catalog

Decision Reality：現在進行式狀態 → 決策

Reality API 的核心不是展示資料，而是回答會影響行動的 現在進行式 狀態：現在是否真的在下雨？現在是否真的在塞車？資料是否夠新，能不能支援即時決策？

{
  "current_state": "drizzle_now",
  "decision_impact": "騎車會被淋濕，走路短程撐傘可接受",
  "recommendation": "騎車穿雨衣；步行可撐傘",
  "confidence": 0.78,
  "limitations": ["最近雨量站距離 4.2 公里"]
}

Now Freshness Contract：現在資料必須夠新

若資料不夠新，Reality API 不可假裝是「現在」。每個可用於即時決策的 signal 都應回報 observed_at、fetched_at、freshness_seconds、staleness。資料過舊時應降級為 stale 或 unknown，並提示不要用於即時決策。

Weather Reality：天氣現狀如何掌握？

天氣不能只看預報。Reality API 會區分 預報 forecast、觀測 observation、現場視覺 visual evidence、nowcasting 臨近推估。當氣象說天晴但現場毛毛雨，常見原因是微氣候、地形雲霧、測站距離、雷達解析度或降雨胞偏移。

Forecast Reality：Weekend / Holiday Planning

幾天後或週末假期的天氣預測有價值，但必須顯示 forecast_uncertainty 與 forecast_divergence。颱風生成、外圍環流、下沉氣流、雲雨帶位置與路徑偏移，都可能讓「預測大雨」與「當地實際很熱很晴」同時成立。

Mountain / Camping Nowcast：山區與露營短時天氣

露營最怕天氣快速變化，因此不能只回答現在有沒有下雨，而要判斷 30–120 分鐘內是短時轉好還是短時轉壞。山區天氣會被地形、地勢、海拔高度、坡向、迎風/背風面、谷地/稜線差異強烈影響。

若當地沒有風速觀測，像 Windy 這類服務通常使用 ECMWF/GFS/ICON 等數值天氣模型推估網格風場，再依位置顯示；Reality API 需標示為 model_estimated_wind，不可假裝是現場實測。

Camera Visual Evidence：攝影機作為現場驗證

攝影機不是唯一資料源，但很適合作為 現場驗證 與 sanity check，用來確認預報、模型、感測器與官方公告是否符合實際畫面。

治理原則：不公開原始 CCTV URL、不做人臉、不做車牌、不長期保存原始影像；對外只輸出 summary / confidence / limitations。

Identity-Level Analysis Governance：身分層級分析治理

公開版 Reality Search 不追蹤個體。車牌辨識、人臉辨識與個體追蹤不是目前公開 API 的核心能力，也不應混入一般天氣、交通、景點與災害查詢。

原則：身分層級的分析只能存在於合法授權、可稽核、政府核准的受管制部署中；不能成為一般公開 Reality Search 的預設能力。

Camera Whitelist Workflow：攝影機白名單介接流程

公共公開攝影機不會直接全量接入。每個來源都必須完成候選來源盤點、授權審查、隱私風險審查、技術可用性檢查與白名單啟用。

1. 候選來源盤點：記錄 provider、頁面來源、地點、用途、更新頻率與初步風險。
2. 授權審查：確認是否允許抓取、AI 分析、展示截圖或僅可連回原頁。
3. 隱私風險審查：排除住宅、學校、醫院、私人空間與容易識別個體的角度。
4. 技術可用性檢查：確認格式、穩定性、更新頻率、延遲與是否需要只存 metadata。
5. 白名單啟用：只允許通過審查的 camera source 進入 on-demand visual evidence pipeline。

Traffic Reality：交通如何測量？

交通不能只用「車速低」判斷。Reality API 會把交通問題拆成 道路可用性、壅塞程度、真卡死/假塞車、資料盲區 四類。

互動式文件

• Swagger UI /docs
• ReDoc /redoc
• OpenAPI JSON /openapi.json

安全限制

• 不支援人臉辨識、車牌辨識、個人追蹤、私人空間監控。
• CCTV / webcam 類資料源必須白名單審查。
• 不公開原始攝影機 URL，不長期保存原始影像。