korean-transit-route

어떤 스킬인가요?

Korean door-to-door public transit routing (subway + bus + walking) via ODsay LIVE API with Kakao geocoding for address-to-address queries. Use when the user asks for 지하철/버스/대중교통 길찾기, 환승 경로, 소요시간, or transit directions between two places in Korea.

설치 방법

프로젝트 폴더에서 아래 명령어를 실행하고, 설치할 에이전트를 선택하세요.

설치 명령을 직접 실행해야 적용됩니다. 지원 에이전트와 필요한 권한·라이선스는 제작자의 안내를 확인하세요.

스킬 원문 파일

# korean-transit-route

## When to use

- "강남에서 잠실 지하철로 어떻게 가?"
- "서울역 → 인천공항 대중교통 경로"
- "환승 가장 적은 경로", "최소 시간 경로"

## Credentials

- 환경변수 `ODSAY_API_KEY` 가 있으면 사용. 없으면 `~/.config/k-skill/secrets.env` 에서 로드.
- ODsay Server 키는 호출 IP 화이트리스트 등록 필수. 발급은 https://lab.odsay.com
- Kakao Local geocoding은 기본 hosted `k-skill-proxy` 경유로 호출하므로 사용자 쪽 `KAKAO_REST_API_KEY` 는 불필요하다. self-host proxy 운영자만 `KAKAO_REST_API_KEY` 를 서버에 설정한다.

## Inputs

자연어 입력에서 출발/도착을 추출. 좌표가 없으면 **반드시 geocoding 먼저** (ODsay는 좌표만 받음).

### Geocoding (필수 선행 단계)

기본 hosted proxy를 사용한다. Proxy가 Kakao Local REST API 키를 서버에서만 주입하고, caller `apiKey` 는 무시한다.

1. `https://k-skill-proxy.nomadamas.org/v1/kakao-local/geocode?q=<주소/장소명>`
2. proxy 내부 fallback: Kakao Local `address.json` → 결과 없으면 `keyword.json`

응답 `documents[0].x`(경도), `.y`(위도) 사용.

```python
import os, urllib.parse, urllib.request, json
PROXY=os.environ.get('KSKILL_PROXY_BASE_URL','https://k-skill-proxy.nomadamas.org').rstrip('/')
def geocode(q):
    url=PROXY+'/v1/kakao-local/geocode?q='+urllib.parse.quote(q)
    with urllib.request.urlopen(url,timeout=10) as resp:
        d=json.loads(resp.read())
    if d.get('documents'):
        doc=d['documents'][0]
        return float(doc['x']), float(doc['y']), doc.get('place_name') or doc.get('address_name')
    return None
```

지하철역명만 정확히 알 때는 ODsay `searchStation` 도 OK 하지만, 도어투도어 결과를 원하면 **실제 출발지/도착지 좌표**를 써야 첫/끝 도보 구간이 계산됨.

## Core call

```bash
set -a; . ~/.config/k-skill/secrets.env; set +a
KEY=$(python3 -c "import os,urllib.parse;print(urllib.parse.quote(os.environ['ODSAY_API_KEY'],safe=''))")
curl -s "https://api.odsay.com/v1/api/searchPubTransPathT?apiKey=${KEY}&SX=${SX}&SY=${SY}&EX=${EX}&EY=${EY}&OPT=0&SearchPathType=${TYPE}"
```

Parameters:
- `SX,SY` 출발 경도/위도, `EX,EY` 도착 경도/위도 (WGS84)
- `OPT`: `0` 추천순(기본), `4` 최소시간, `5` 최소환승
- `SearchPathType`: `0` 지하철+버스, `1` 지하철만, `2` 버스만

## Response shape

`result.path[]` 배열, 각 path:
- `pathType`: 1=지하철, 2=버스, 3=지하철+버스
- `info.totalTime`(분), `info.payment`(원), `info.subwayTransitCount`, `info.busTransitCount`, `info.totalWalk`(m), `info.firstStartStation`, `info.lastEndStation`
- `subPath[]`: 구간별. `trafficType` 1=지하철 2=버스 3=도보. 지하철이면 `lane[0].name`, `startName`, `endName`, `passStopList.stations[]`(경유역)

## Recommended output (door-to-door)

`subPath` 의 각 구간을 `trafficType` 별로 표시. 첫/끝 도보 구간은 출발지·도착지에서 역까지 실제 도보를 의미하므로 **반드시 포함**.

```
🚇 범안로95번길 32 → SKT타워
경로 1: 54분 · 1,950원 · 환승 2회 · 도보 688m
  🚶 도보 1분
  🚌 19번 부천범박힐스테이트 → 역곡역 (9분)
  🚶 도보 2분
  🚇 1호선 역곡 → 종각 (15정거장, 35분)
  🚶 도보 7분
```

3개 이내 경로 비교 권장. `OPT=4`(최소시간) / `OPT=5`(최소환승) 옵션을 사용자가 선호 표시하면 그쪽으로 호출.

## Done when

- 출발지와 도착지가 geocoding 되었거나, 좌표/역명이 명확히 확인되었다.
- ODsay 응답에서 1개 이상 경로가 정리되었다.
- 각 경로의 총 소요시간, 요금, 환승 횟수, 총 도보 거리가 포함되었다.
- 첫/끝 도보 구간이 포함된 door-to-door 요약을 보여줬다.
- upstream API 키가 응답에 노출되지 않았다.

## Helpers

좌표 모르고 역명만 아는 경우 — `searchStation` 으로 변환:

```bash
curl -s "https://api.odsay.com/v1/api/searchStation?apiKey=${KEY}&stationName=강남&CID=1000"
```

`CID=1000` = 수도권. 결과 `result.station[].x,y` 가 좌표.

## Limits

- 현재 ODsay 공식 Basic 상품 기준 무료 체험은 일 1,000건(6개월)이다. `searchPubTransPathT` + `searchStation` 호출이 합산되니 한 질문당 호출 최소화.
- 응답에 `error` 키 있으면 즉시 사용자에게 표시(ApiKey/IP 문제 진단에 유용).
- 한국 외 좌표는 지원 안 함.

## Failure modes

- ODsay `error` 응답: `msg` 필드를 그대로 사용자에게 표시하고, ApiKey 미등록 또는 IP 화이트리스트 누락 가능성을 안내한다.
- Kakao geocoding 결과 없음: 주소/장소명을 다시 확인하거나 더 구체적인 표현을 요청한다.
- 좌표는 있으나 ODsay 경로 없음: 대중교통 미개통 지역, 도보 가능 거리, 또는 해상/공항 구간일 수 있다. 사용자에게 확인한다.
- quota 초과: 일일 한도 도달 시 추가 호출을 중단하고 사용자에게 알린다.

## Don'ts

- 카카오맵/네이버지도 directions API로 대중교통 라우팅 시도하지 말 것 (둘 다 운전·도보만 공개).
- 키를 절대 응답에 노출하지 말 것.

# DISCLAIMER — `korean-transit-route`

이 스킬은 제3자 상표권자·서비스 운영사의 공식 기능 또는 공식 지원 도구가 아니며, 공식 제휴·후원·승인·인증 또는 협업한 사실이 전혀 없습니다. 상표와 서비스명은 기능, 조회 대상 또는 호환 대상을 설명하기 위해서만 사용합니다.

대법원 2005. 6. 10. 선고 [2005도1637 판결](https://www.law.go.kr/LSW/precInfoP.do?precSeq=83920)(소니용 리모컨 사건)은 기능 설명용 표장과 출처표시를 구별했습니다. [상표법 제2조](https://www.law.go.kr/법령/상표법/제2조), [제89조](https://www.law.go.kr/법령/상표법/제89조), [제90조](https://www.law.go.kr/법령/상표법/제90조), [제108조](https://www.law.go.kr/법령/상표법/제108조)에 따른 출처 혼동 판단은 별도입니다.

대법원 2022. 5. 12. 선고 [2021도1533 판결](https://www.law.go.kr/LSW/precInfoP.do?precSeq=221765)은 공개정보의 기계적 수집만으로 곧바로 [정보통신망법 제48조](https://www.law.go.kr/법령/정보통신망이용촉진및정보보호등에관한법률/제48조) 위반이 되는 것은 아니라고 볼 수 있는 사정을 제시했지만, 크롤링의 일반적 허용을 뜻하지 않습니다. [저작권법 제93조](https://www.law.go.kr/법령/저작권법/제93조)의 데이터베이스 권리와 [형법 제314조 제2항](https://www.law.go.kr/법령/형법/제314조)의 서비스 장애·영업 방해 책임은 별도입니다.

- 공개정보 자동 수집은 반드시 개인의 정보 조회용으로만 사용하고 조직적·대량 크롤링이나 별도 DB 구축을 하지 않습니다.
- 공식 API의 quota·약관을 지키고 접근통제·차단을 우회하지 않습니다.
- 공격적 polling이나 병렬 대량 호출로 정상 서비스를 방해하지 않습니다.

이 문서는 적법성을 보증하는 법률 자문이 아닙니다.

# 상표 사용 법적 고지 — `korean-transit-route`

이 스킬에서 `ODsay`와 `카카오` 명칭은 대중교통 경로 조회 및 주소 좌표 변환에 사용하는 **대상 API와 서비스**를 식별하기 위해 사용한다. k-skill의 출처를 해당 운영사로 표시하려는 사용이 아니다.

대법원 2005. 6. 10. 선고 [2005도1637 판결](https://www.law.go.kr/LSW/precInfoP.do?precSeq=83920)은 타인의 표장을 출처표시가 아니라 상품 기능 또는 적용 기종을 밝히기 위해 사용하고 상표 사용으로 인식될 수 없는 경우 침해가 아니라고 판시했다. [상표법 제2조](https://www.law.go.kr/법령/상표법/제2조), [제89조](https://www.law.go.kr/법령/상표법/제89조), [제90조](https://www.law.go.kr/법령/상표법/제90조), [제108조](https://www.law.go.kr/법령/상표법/제108조)와 대법원 [2011다18802](https://www.law.go.kr/LSW/precInfoP.do?precSeq=167457), [2019후10418](https://law.go.kr/LSW/precInfoP.do?mode=0&precSeq=230725) 판결에 따라 실제 거래계에서 출처표시로 기능하는지는 표시 태양과 사용 경위 등을 종합해 판단해야 한다.

따라서 이 명칭은 필요한 범위의 평문으로만 사용하고, 별도 근거 없이 로고, 공식·제휴·후원·인증·파트너 표현을 사용하지 않는다. 각 상표의 권리는 해당 권리자에게 있다. 이 문서는 API 이용약관, 저작권, 데이터베이스권, 부정경쟁방지법, 개인정보 또는 접근 방식의 적법성을 판단하지 않는다.

전체 검토: [제3자 상표의 기능 설명·호환 대상 표시 검토](https://github.com/NomaDamas/k-skill/blob/dev/docs/legal/trademark-use-review.md)

{
  "name": "korean-transit-route",
  "description": "Korean door-to-door public transit routing (subway + bus + walking) via ODsay LIVE API with Kakao geocoding for address-to-address queries. Use when the user asks for 지하철/버스/대중교통 길찾기, 환승 경로, 소요시간, or transit directions between two places in Korea.",
  "profiles": [
    "proxy",
    "lookup"
  ],
  "frontmatter": "name: korean-transit-route\ndescription: Korean door-to-door public transit routing (subway + bus + walking) via ODsay LIVE API with Kakao geocoding for address-to-address queries. Use when the user asks for 지하철/버스/대중교통 길찾기, 환승 경로, 소요시간, or transit directions between two places in Korea.\nlicense: MIT\nmetadata:\n  category: transit\n  locale: ko-KR\n  phase: v1"
}

---
name: korean-transit-route
description: Korean door-to-door public transit routing (subway + bus + walking) via ODsay LIVE API with Kakao geocoding for address-to-address queries. Use when the user asks for 지하철/버스/대중교통 길찾기, 환승 경로, 소요시간, or transit directions between two places in Korea.
license: MIT
metadata:
  category: transit
  locale: ko-KR
  phase: v1
---

# korean-transit-route

<!-- k-skill:cli-stub — generated by scripts/generate-skill-stubs.js; edit skill.json / instruction.md instead -->

## Get the full instructions (required first step)

Run this and follow its output as the primary instructions for this skill:

```bash
npx -y @nomadamas/k-skill@0 instruct korean-transit-route
```

The CLI detects the current runtime (Dolshoi vault/CloakBrowser vs generic) and prints only the applicable instructions, always up to date. Helper files bundled with the CLI are listed by:

```bash
npx -y @nomadamas/k-skill@0 files korean-transit-route
```

If `npx` is unavailable, install Node.js 18+ or follow https://github.com/NomaDamas/k-skill#readme, or read the source instructions at https://github.com/NomaDamas/k-skill/blob/main/korean-transit-route/instruction.md.

## Legal disclaimer (required)

This skill is not an official feature of, officially supported by, affiliated with, sponsored by, approved by, or developed in collaboration with any third-party trademark owner or service operator it identifies. Third-party names are used only to describe the skill's function, lookup target, or compatibility.

Any automated collection of publicly accessible information must be limited to personal, non-organizational lookup. Do not use this skill for systematic or bulk crawling, database building, access-control or block circumvention, or conduct that interferes with a third party's business or service.

Read the full Korean legal disclaimer, including the cited Korean Supreme Court precedents and statutory limits, before use:

```bash
npx -y @nomadamas/k-skill@0 read korean-transit-route references/DISCLAIMER.md
```

## Hard rules even without the CLI

- Never execute payment, message/email delivery, final submission, cancellation, or public posting without the user's explicit approval immediately beforehand.
- Never ask for, print, or store plaintext credentials in chat, files, or shell arguments.
- Never bypass legal, physical-presence, CAPTCHA, identity-proofing, or electronic-signature boundaries.