korea-weather

Korea Weather

這個技能做什麼

透過 k-skill-proxy 代理查詢韓國氣象廳短期預報服務，並摘要韓國天氣。
使用者不需要自行申請個人 OpenAPI key，只需在代理伺服器上設定 KMA_OPEN_API_KEY。

使用時機

• 「首爾市廳附近現在天氣如何？」
• 「告訴我釜山天氣」
• 「我想根據經緯度查詢韓國短期預報」

前置需求

• 選用：jq
• 選用：KSKILL_PROXY_BASE_URL（僅在使用自架代理時設定。若未設定，將使用預設託管代理 https://k-skill-proxy.nomadamas.org）

必要的環境變數

• 無。KSKILL_PROXY_BASE_URL 為選用，若未設定則使用預設託管代理 https://k-skill-proxy.nomadamas.org。

使用者無需直接處理公共數據入口網站的氣象廳 API key。/v1/korea-weather/forecast 路由會透過預設託管代理呼叫，上游的 KMA_OPEN_API_KEY 僅由代理伺服器管理。僅在使用自架代理時才需設定 KSKILL_PROXY_BASE_URL。

輸入

• 網格座標：nx、ny
• 或經緯度：lat、lon
• 選用：baseDate、baseTime

若省略 baseDate / baseTime，代理會自動選取韓國標準時間最新的短期預報發布時間。

工作流程

1. 解析代理基礎 URL

如果設定了 KSKILL_PROXY_BASE_URL，則使用該值；否則使用預設託管代理 https://k-skill-proxy.nomadamas.org。

2. 查詢短期預報端點

如果已有網格座標，直接帶入；如果只有經緯度，則直接傳給代理。

BASE="${KSKILL_PROXY_BASE_URL:-https://k-skill-proxy.nomadamas.org}"
curl -fsS --get "${BASE}/v1/korea-weather/forecast" \
  --data-urlencode 'lat=37.5665' \
  --data-urlencode 'lon=126.9780'

網格座標範例：

BASE="${KSKILL_PROXY_BASE_URL:-https://k-skill-proxy.nomadamas.org}"
curl -fsS --get "${BASE}/v1/korea-weather/forecast" \
  --data-urlencode 'nx=60' \
  --data-urlencode 'ny=127' \
  --data-urlencode 'baseDate=20260405' \
  --data-urlencode 'baseTime=0500'

3. 保守地摘要回應

盡可能先摘要以下項目：

• TMP：氣溫
• SKY：天空狀態
• PTY：降水型態
• POP：降水機率
• PCP：降水量
• SNO：積雪
• REH：濕度
• WSD：風速

回應中也應包含查詢時間與 baseDate / baseTime。

完成條件

• 已整理出請求位置的短期預報回應
• 已標明查詢時間與預報發布時間
• 上游 key 未暴露給客戶端

失敗模式

• 代理上游 key 未設定，或託管/自架路由故障
• nx / ny 或 lat / lon 不完整
• 氣象廳配額超標或上游故障
• 所選發布時間的預報尚未準備好

備註

• 官方 API 使用 nx / ny 網格，但代理也接受 lat / lon，並在內部轉換為網格。
• 短期預報類別主要關注 TMP、SKY、PTY、POP、PCP、SNO、REH、WSD 等。
• 代理操作/環境變數設定請參考 docs/features/k-skill-proxy.md。