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

/v1/seoul-bike/*

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]

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

  를 참고한다.