seoul-bike

name	seoul-bike
description	서울 따릉이 실시간 대여소의 대여 가능 자전거와 빈 거치대를 좌표 주변 또는 대여소 이름으로 조회한다.
license	MIT
metadata	{"category":"transit","locale":"ko-KR","phase":"v1"}

Seoul Bike (따릉이)

What this skill does

서울 열린데이터 광장의 따릉이 실시간 대여정보를 k-skill-proxy 경유로 조회해 대여 가능 자전거 수와 빈 거치대 수를 요약한다.

When to use

• "지금 여기서 따릉이 빌릴 수 있어?"
• "광화문 근처 빈 거치대 있어?"
• "강남역 따릉이 대여소에 자전거 몇 대 남았어?"

Prerequisites

• Python 3 표준 라이브러리만 사용한다.
• optional: KSKILL_PROXY_BASE_URL (self-host·별도 프록시를 쓸 때만 설정. 비우면 기본 hosted https://k-skill-proxy.nomadamas.org 를 사용한다.)

Required environment variables

없음. 사용자가 개인 서울 열린데이터 광장 OpenAPI key를 직접 발급할 필요는 없다. /v1/seoul-bike/* routes는 기본 hosted proxy에서 호출하고, upstream key는 proxy 서버 쪽에만 보관한다.

Single entrypoint

python3 "$SKILL_DIR/scripts/seoul_bike.py" <subcommand> [args]

첫 사용 시 Bash(python3 *seoul_bike.py:*) 패턴 한 번만 승인하면 이후 호출은 모두 자동 허용된다.

Subcommands

명령	설명
nearby --lat LAT --lon LON [--radius-m 500] [--limit 10] [--json]	좌표 주변 실시간 대여소 조회
search <키워드> [--limit 10] [--json]	대여소 이름에 키워드가 포함된 실시간 상태 검색
realtime [--start-index 1 --end-index 1000]	실시간 대여정보 원문 JSON 페이지 조회

Workflow

1. 현재 위치 주변 대여소 조회

python3 "$SKILL_DIR/scripts/seoul_bike.py" nearby --lat 37.5717 --lon 126.9763 --radius-m 500

요약 항목:

• 대여소명
• 대여 가능 자전거 수 (parkingBikeTotCnt)
• 빈 거치대 수 (rackTotCnt - parkingBikeTotCnt)
• 거리(m)
• 조회 시각(proxy.requested_at)

2. 대여소 이름 검색

python3 "$SKILL_DIR/scripts/seoul_bike.py" search "광화문" --limit 5

3. Proxy endpoints

• GET /v1/seoul-bike/realtime?startIndex=1&endIndex=1000 → 서울 bikeList 실시간 대여정보
• GET /v1/seoul-bike/stations?startIndex=1&endIndex=1000 → 서울 tbCycleStationInfo 대여소 마스터 정보
• GET /v1/seoul-bike/nearby?lat=37.5717&lon=126.9763&radius_m=500&limit=10 → proxy-side 주변 대여소 필터링

Done when

• 대여 가능 자전거 수와 빈 거치대 수가 정리되어 있다.
• live data 기준 조회 시각이 명시되어 있다.
• upstream key가 클라이언트에 노출되지 않았다.

Failure modes

• proxy upstream key 미설정 (SEOUL_OPEN_API_KEY 없음)
• 서울 열린데이터 광장 quota 초과
• 실시간 API가 빈 행 또는 일시 오류를 반환
• 좌표가 없거나 반경 안에 대여소가 없음

Notes

• 실시간 데이터는 계속 변하므로 답변에 조회 시각을 함께 적는다.
• 예약/대여 자동화는 하지 않는다. 조회 전용 스킬이다.
• proxy 운영/환경변수 설정은 docs/features/k-skill-proxy.md 를 참고한다.