seoul-subway

---
name: seoul-subway
description: Seoul Subway assistant for real-time arrivals, route planning, and service alerts (Korean/English)
model: sonnet
metadata: {"moltbot":{"emoji":"🚇","requires":{"bins":["curl","jq"]}}}
homepage: https://github.com/dukbong/seoul-subway
user-invocable: true
---

# Seoul Subway Skill

Query real-time Seoul Subway information. **No API key required** - uses proxy server.

## Features

| Feature | Description | Trigger Example (KO) | Trigger Example (EN) |
|---------|-------------|----------------------|----------------------|
| Real-time Arrival | Train arrival times by station | "강남역 도착정보" | "Gangnam station arrivals" |
| Station Search | Line and station code lookup | "강남역 몇호선?" | "What line is Gangnam?" |
| Route Search | Shortest path with time/fare | "신도림에서 서울역" | "Sindorim to Seoul Station" |
| Service Alerts | Delays, incidents, non-stops | "지하철 지연 있어?" | "Any subway delays?" |
| **Last Train** | Last train times by station | "홍대 막차 몇 시야?" | "Last train to Hongdae?" |
| **Exit Info** | Exit numbers for landmarks | "코엑스 몇 번 출구?" | "Which exit for COEX?" |
| **Accessibility** | Elevators, escalators, wheelchair lifts | "강남역 엘리베이터" | "Gangnam elevators" |
| **Quick Exit** | Best car for facilities | "강남역 빠른하차" | "Gangnam quick exit" |
| **Restrooms** | Restroom locations | "강남역 화장실" | "Gangnam restrooms" |

### Natural Language Triggers / 자연어 트리거

다양한 자연어 표현을 인식합니다:

#### Real-time Arrival / 실시간 도착
| English | 한국어 |
|---------|--------|
| "When's the next train at Gangnam?" | "강남 몇 분 남았어?" |
| "Trains at Gangnam" | "강남 열차" |
| "Gangnam arrivals" | "강남 언제 와?" |
| "Next train to Gangnam" | "다음 열차 강남" |

#### Route Search / 경로 검색
| English | 한국어 |
|---------|--------|
| "How do I get to Seoul Station from Gangnam?" | "강남에서 서울역 어떻게 가?" |
| "Gangnam → Seoul Station" | "강남 → 서울역" |
| "Gangnam to Seoul Station" | "강남에서 서울역 가는 길" |
| "Route from Gangnam to Hongdae" | "강남부터 홍대까지" |

#### Service Alerts / 운행 알림
| English | 한국어 |
|---------|--------|
| "Is Line 2 running normally?" | "2호선 정상 운행해?" |
| "Any delays on Line 1?" | "1호선 지연 있어?" |
| "Subway status" | "지하철 상황" |
| "Line 3 alerts" | "3호선 알림" |

#### Last Train / 막차 시간
| English | 한국어 |
|---------|--------|
| "Last train to Gangnam?" | "강남 막차 몇 시야?" |
| "When is the last train at Hongdae?" | "홍대입구 막차 시간" |
| "Final train to Seoul Station" | "서울역 막차" |
| "Last train on Saturday?" | "토요일 막차 시간" |

#### Exit Info / 출구 정보
| English | 한국어 |
|---------|--------|
| "Which exit for COEX?" | "코엑스 몇 번 출구?" |
| "Exit for Lotte World" | "롯데월드 출구" |
| "DDP which exit?" | "DDP 몇 번 출구?" |
| "Gyeongbokgung Palace exit" | "경복궁 나가는 출구" |

#### Accessibility / 접근성 정보
| English | 한국어 |
|---------|--------|
| "Gangnam station elevators" | "강남역 엘리베이터" |
| "Escalators at Seoul Station" | "서울역 에스컬레이터" |
| "Wheelchair lifts at Jamsil" | "잠실역 휠체어리프트" |
| "Accessibility info for Hongdae" | "홍대입구 접근성 정보" |

#### Quick Exit / 빠른하차
| English | 한국어 |
|---------|--------|
| "Quick exit at Gangnam" | "강남역 빠른하차" |
| "Which car for elevator?" | "엘리베이터 몇 번째 칸?" |
| "Best car for exit 3" | "3번 출구 가까운 칸" |
| "Fastest exit at Samsung" | "삼성역 빠른 하차 위치" |

#### Restrooms / 화장실
| English | 한국어 |
|---------|--------|
| "Restrooms at Gangnam" | "강남역 화장실" |
| "Where's the bathroom at Myeongdong?" | "명동역 화장실 어디야?" |
| "Accessible restroom at Seoul Station" | "서울역 장애인 화장실" |
| "Baby changing station at Jamsil" | "잠실역 기저귀 교환대" |

---

## First Time Setup / 첫 사용 안내

When you first use this skill, you'll see a permission prompt for the proxy domain.

처음 사용 시 프록시 도메인 접근 확인 창이 뜹니다.

**Select / 선택:** `Yes, and don't ask again for vercel-proxy-henna-eight.vercel.app`

This only needs to be done once. / 한 번만 하면 됩니다.

---

## Proxy API Reference

All API calls go through the proxy server. No API keys needed for users.

### Base URL

```
https://vercel-proxy-henna-eight.vercel.app
```

### 1. Real-time Arrival Info

**Endpoint**
```
GET /api/realtime/{station}?start=0&end=10
```

**Parameters**

| Parameter | Required | Description |
|-----------|----------|-------------|
| station | Yes | Station name (Korean, URL-encoded) |
| start | No | Start index (default: 0) |
| end | No | End index (default: 10) |
| format | No | `formatted` (markdown, default) or `raw` (JSON) |
| lang | No | `ko` (default) or `en` |

**Response Fields**

| Field | Description |
|-------|-------------|
| `subwayId` | Line ID (1002=Line 2, 1077=Sinbundang) |
| `trainLineNm` | Direction (e.g., "성수행 - 역삼방면") |
| `arvlMsg2` | Arrival time (e.g., "4분 20초 후") |
| `arvlMsg3` | Current location |
| `isFastTrain` | Fast train flag (1=급행) |

**Example**
```bash
curl "https://vercel-proxy-henna-eight.vercel.app/api/realtime/강남"
```

---

### 2. Station Search

**Endpoint**
```
GET /api/stations?station={name}&start=1&end=10
```

**Parameters**

| Parameter | Required | Description |
|-----------|----------|-------------|
| station | Yes | Station name to search |
| start | No | Start index (default: 1) |
| end | No | End index (default: 10) |

**Response Fields**

| Field | Description |
|-------|-------------|
| `STATION_CD` | Station code |
| `STATION_NM` | Station name |
| `LINE_NUM` | Line name (e.g., "02호선") |
| `FR_CODE` | External station code |

**Example**
```bash
curl "https://vercel-proxy-henna-eight.vercel.app/api/stations?station=강남"
```

---

### 3. Route Search

**Endpoint**
```
GET /api/route?dptreStnNm={departure}&arvlStnNm={arrival}
```

**Parameters**

| Parameter | Required | Description |
|-----------|----------|-------------|
| dptreStnNm | Yes | Departure station |
| arvlStnNm | Yes | Arrival station |
| searchDt | No | Datetime (yyyy-MM-dd HH:mm:ss) |
| searchType | No | duration / distance / transfer |
| format | No | `formatted` (markdown, default) or `raw` (JSON) |
| lang | No | `ko` (default) or `en` |

**Response Fields**

| Field | Description |
|-------|-------------|
| `totalDstc` | Total distance (m) |
| `totalreqHr` | Total time (seconds) |
| `totalCardCrg` | Fare (KRW) |
| `paths[].trainno` | Train number |
| `paths[].trainDptreTm` | Departure time |
| `paths[].trainArvlTm` | Arrival time |
| `paths[].trsitYn` | Transfer flag |

**Example**
```bash
curl "https://vercel-proxy-henna-eight.vercel.app/api/route?dptreStnNm=신도림&arvlStnNm=서울역"
```

---

### 4. Service Alerts

**Endpoint**
```
GET /api/alerts?pageNo=1&numOfRows=10&format=enhanced
```

**Parameters**

| Parameter | Required | Description |
|-----------|----------|-------------|
| pageNo | No | Page number (default: 1) |
| numOfRows | No | Results per page (default: 10) |
| lineNm | No | Filter by line |
| format | No | `default` or `enhanced` (structured response) |

**Response Fields (Default)**

| Field | Description |
|-------|-------------|
| `ntceNo` | Notice number |
| `ntceSj` | Notice title |
| `ntceCn` | Notice content |
| `lineNm` | Line name |
| `regDt` | Registration date |

**Response Fields (Enhanced)**

| Field | Description |
|-------|-------------|
| `summary.delayedLines` | Lines with delays |
| `summary.suspendedLines` | Lines with service suspended |
| `summary.normalLines` | Lines operating normally |
| `alerts[].lineName` | Line name (Korean) |
| `alerts[].lineNameEn` | Line name (English) |
| `alerts[].status` | `normal`, `delayed`, or `suspended` |
| `alerts[].severity` | `low`, `medium`, or `high` |
| `alerts[].title` | Alert title |

**Example**
```bash
# Default format
curl "https://vercel-proxy-henna-eight.vercel.app/api/alerts"

# Enhanced format with status summary
curl "https://vercel-proxy-henna-eight.vercel.app/api/alerts?format=enhanced"
```

---

### 5. Last Train Time

> **참고:** 이 API는 주요 역 77개의 막차 시간을 정적 데이터로 제공합니다.
> 서울교통공사 2025년 1월 기준 데이터입니다.
>
> **지원 역 (77개):**
> 가산디지털단지, 강남, 강남구청, 강변, 건대입구, 경복궁, 고속터미널, 공덕, 광나루, 광화문, 교대, 구로, 군자, 김포공항, 노량진, 당산, 대림, 동대문, 동대문역사문화공원, 디지털미디어시티, 뚝섬, 마포구청, 명동, 모란, 몽촌토성, 복정, 불광, 사가정, 사당, 삼각지, 삼성, 상봉, 서울대입구, 서울역, 선릉, 성수, 수유, 시청, 신논현, 신당, 신도림, 신사, 신촌, 안국, 압구정, 약수, 양재, 여의도, 역삼, 연신내, 영등포, 옥수, 올림픽공원, 왕십리, 용산, 을지로3가, 을지로4가, 을지로입구, 응암, 이대, 이촌, 이태원, 인천공항1터미널, 인천공항2터미널, 잠실, 정자, 종각, 종로3가, 종합운동장, 천호, 청담, 충무로, 판교, 합정, 혜화, 홍대입구, 효창공원앞

**Endpoint**
```
GET /api/last-train/{station}?direction=up&weekType=1
```

**Parameters**

| Parameter | Required | Description |
|-----------|----------|-------------|
| station | Yes | Station name (Korean or English) |
| direction | No | `up`, `down`, or `all` (default: all) |
| weekType | No | `1`=Weekday, `2`=Saturday, `3`=Sunday/Holiday (default: auto) |

**Response Fields**

| Field | Description |
|-------|-------------|
| `station` | Station name (Korean) |
| `stationEn` | Station name (English) |
| `lastTrains[].direction` | Direction (Korean) |
| `lastTrains[].directionEn` | Direction (English) |
| `lastTrains[].time` | Last train time (HH:MM) |
| `lastTrains[].weekType` | Day type (Korean) |
| `lastTrains[].weekTypeEn` | Day type (English) |
| `lastTrains[].line` | Line name |
| `lastTrains[].lineEn` | Line name (English) |
| `lastTrains[].destination` | Final destination |
| `lastTrains[].destinationEn` | Destination (English) |

**Example**
```bash
# Auto-detect day type
curl "https://vercel-proxy-henna-eight.vercel.app/api/last-train/홍대입구"

# English station name
curl "https://vercel-proxy-henna-eight.vercel.app/api/last-train/Hongdae"

# Specific direction and day
curl "https://vercel-proxy-henna-eight.vercel.app/api/last-train/강남?direction=up&weekType=1"
```

---

### 6. Exit Information

> **참고:** 이 API는 주요 역 77개의 출구 정보를 정적 데이터로 제공합니다.
>
> **지원 역 (77개):**
> 가산디지털단지, 강남, 강남구청, 강변, 건대입구, 경복궁, 고속터미널, 공덕, 광나루, 광화문, 교대, 구로, 군자, 김포공항, 노량진, 당산, 대림, 동대문, 동대문역사문화공원, 디지털미디어시티, 뚝섬, 마포구청, 명동, 모란, 몽촌토성, 복정, 불광, 사가정, 사당, 삼각지, 삼성, 상봉, 서울대입구, 서울역, 선릉, 성수, 수유, 시청, 신논현, 신당, 신도림, 신사, 신촌, 안국, 압구정, 약수, 양재, 여의도, 역삼, 연신내, 영등포, 옥수, 올림픽공원, 왕십리, 용산, 을지로3가, 을지로4가, 을지로입구, 응암, 이대, 이촌, 이태원, 인천공항1터미널, 인천공항2터미널, 잠실, 정자, 종각, 종로3가, 종합운동장, 천호, 청담, 충무로, 판교, 합정, 혜화, 홍대입구, 효창공원앞

**Endpoint**
```
GET /api/exits/{station}
```

**Parameters**

| Parameter | Require

... (truncated)