seoul-subway-arrival

首爾地鐵到站資訊

此技能的功能

透過 k-skill-proxy 查詢首爾開放資料廣場的即時地鐵到站資訊 Open API，摘要各車站的預計到站列車資訊。

使用時機

• 「江南站現在還有幾分鐘到站？」
• 「首爾站 1 號線到站資訊」
• 「整理一下蠶室站即將進站的列車」

前置需求

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

必要的環境變數

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

使用者無需自行申請首爾開放資料廣場的 OpenAPI 金鑰。/v1/seoul-subway/arrival 路由由預設託管代理呼叫，上游金鑰僅存放於代理伺服器端。僅在使用自架代理時才需設定 KSKILL_PROXY_BASE_URL。

代理解析順序

1. 若 KSKILL_PROXY_BASE_URL 存在，則使用該值。
2. 若不存在或為空值，則使用預設託管代理 https://k-skill-proxy.nomadamas.org。
3. 僅在自行運作代理時，才需在伺服器端設定代理的上游金鑰。

客戶端/使用者端不會直接處理上游金鑰。

輸入

• 車站名稱
• 選用：要取得的筆數

工作流程

1. 解析代理基礎 URL

若 KSKILL_PROXY_BASE_URL 存在則使用該值，若不存在或為空則使用預設託管代理 https://k-skill-proxy.nomadamas.org。

2. 查詢官方車站到站端點

代理會在伺服器端注入首爾即時地鐵 API 金鑰，並僅以唯讀端點公開依車站名稱查詢的即時到站資訊。

BASE="${KSKILL_PROXY_BASE_URL:-https://k-skill-proxy.nomadamas.org}"
curl -fsS --get "${BASE}/v1/seoul-subway/arrival" \
  --data-urlencode 'stationName=강남'

如有需要，可使用 startIndex 和 endIndex 調整回應範圍。

3. 摘要回應

盡可能先摘要以下項目：

• 路線
• 上行/下行或外線/內線
• 第一則到站訊息
• 第二則到站訊息
• 預計到站時間（若有，以秒為單位）

4. 謹慎處理即時資料

即時資料可能每隔幾秒就變動，因此回答時應一併記錄查詢時間。

完成條件

• 已整理出請求車站的預計到站列車
• 已標明即時資料的基準時間
• 上游金鑰未暴露給客戶端

失敗模式

• 代理上游金鑰未設定
• 配額超標
• 車站名稱標示不一致

備註

• 首爾開放資料廣場指南指出，即時地鐵 Open API 可能設有每日呼叫限制
• 代理運作/環境變數設定請參考 docs/features/k-skill-proxy.md
• 端點路徑可能因 API 版本變更，若失敗請再次確認資料集主控台的最新範例 URL