seoul-subwaylisted

# seoul-subway ソウル特別市のオープンAPIで、地下鉄のリアルタイム到着予測を取得するスキル。到着予測API(realtimeStationArrival)と列車位置API(realtimePosition)の両方で、サンプルキーのまま実データが取れることを 2026-09-22 に再実測した(後述の「再現可能な実データ確認例」)。本番利用には無料キーを取得する。 ## キーの取得 ソウルオープンデータ広場(서울 열린데이터광장) https://data.seoul.go.kr/ で会員登録し、「서울교통공사 실시간 지하철 도착정보」の活用申請をすると即時に認証キーが発行される(無料)。 ## 基本の流れ 1. 駅名を**韓国語表記**にする(APIの入力は韓国語) 2. リアルタイム到着APIを呼ぶ 3. 方面・路線で絞って読む ### 1. 駅名を韓国語にする 日本の旅行者が使う駅名の主な対応(抜粋): | 日本語 | 韓国語(API入力) | 路線 | | --- | --- | --- | | ソウル駅 | 서울역 | 1, 4, 空港鉄道 | | 明洞 | 명동 | 4 | | 弘大入口 | 홍대입구 | 2, 空港鉄道, 京義中央 | | 東大門歴史文化公園 | 동대문역사문화공원 | 2, 4, 5 | | 江南 | 강남 | 2, 新盆唐 | | 新沙 | 신사 | 3 | | 梨泰院 | 이태원 | 6 | | 仁川空港1ターミナル | 인천공항1터미널 | 空港鉄道 | 主要な観光駅44件の対応表を **`data/stations-ja-ko.csv`** に同梱している(日本語 → API入力用韓国語 → 路線)。表にない駅は、全駅の日本語・中国語・英語対応表であるソウル交通公社の公式データ「역명다국어표기」(公共データポータル 15044232、ファイルデータ)を使う: https://www.data.go.kr/data/15044232/fileData.do ### 2. リアルタイム到着APIを呼ぶ ```bash # 駅名(홍대입구)はパーセントエンコードして渡す curl -s "http://swopenapi.seoul.go.kr/api/subway/{SEOUL_KEY}/json/realtimeStationArrival/0/10/%ED%99%8D%EB%8C%80%EC%9E%85%EA%B5%AC" ``` 末尾のパス要素が駅名(韓国語)。curlはパスをエンコードしないので、駅名は必ずパーセントエンコードしてからURLに埋め込む。エンコード例: ```bash STATION=$(printf '%s' "홍대입구" | jq -sRr @uri) # jq がある場合 # または python3 -c 'import urllib.parse,sys; print(urllib.parse.quote(sys.argv[1]))' "홍대입구" curl -s "http://swopenapi.seoul.go.kr/api/subway/{SEOUL_KEY}/json/realtimeStationArrival/0/10/${STATION}" ``` `0/10` は取得範囲(開始/件数)。 ### 3. レスポンスの読み方 `realtimeStationArrivalList` 配列の各要素: - `trainL