Back to Details

seoul-bike

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Seoul Bike (따릉이)

Seoul Bike (따릉이)

What this skill does

What this skill does

서울 열린데이터 광장의 따릉이 실시간 대여정보를 
k-skill-proxy
경유로 조회해 대여 가능 자전거 수와 빈 거치대 수를 요약한다.
通过
k-skill-proxy
查询首尔开放数据广场的共享单车（따릉이）实时租赁信息，汇总可借车辆数和空车位数量。

When to use

When to use

  • "지금 여기서 따릉이 빌릴 수 있어?"
  • "광화문 근처 빈 거치대 있어?"
  • "강남역 따릉이 대여소에 자전거 몇 대 남았어?"
  • "现在这里能借共享单车吗？"
  • "光化门附近有空车位吗？"
  • "江南站共享单车租赁点还剩多少辆车？"

Prerequisites

Prerequisites

  • Python 3 표준 라이브러리만 사용한다.
  • optional: 
    KSKILL_PROXY_BASE_URL
    (self-host·별도 프록시를 쓸 때만 설정. 비우면 기본 hosted 
    https://k-skill-proxy.nomadamas.org
    를 사용한다.)
  • 仅使用Python 3标准库。
  • optional: 
    KSKILL_PROXY_BASE_URL
    （仅在自托管或使用独立代理时设置。留空则使用默认托管地址
    https://k-skill-proxy.nomadamas.org
    ）。

Required environment variables

Required environment variables

없음. 사용자가 개인 서울 열린데이터 광장 OpenAPI key를 직접 발급할 필요는 없다. 
/v1/seoul-bike/*
routes는 기본 hosted proxy에서 호출하고, upstream key는 proxy 서버 쪽에만 보관한다.
无。用户无需自行申请首尔开放数据广场的个人OpenAPI密钥。
/v1/seoul-bike/*
路由由默认托管代理调用，上游密钥仅保存在代理服务器端。

Single entrypoint

Single entrypoint

bash
python3 "$SKILL_DIR/scripts/seoul_bike.py" <subcommand> [args]
첫 사용 시 
Bash(python3 *seoul_bike.py:*)
패턴 한 번만 승인하면 이후 호출은 모두 자동 허용된다.
bash
python3 "$SKILL_DIR/scripts/seoul_bike.py" <subcommand> [args]
首次使用时，只需批准一次
Bash(python3 *seoul_bike.py:*)
模式，后续调用将自动允许。

Subcommands

Subcommands

명령설명
nearby --lat LAT --lon LON [--radius-m 500] [--limit 10] [--json]
좌표 주변 실시간 대여소 조회
search <키워드> [--limit 10] [--json]
대여소 이름에 키워드가 포함된 실시간 상태 검색
realtime [--start-index 1 --end-index 1000]
실시간 대여정보 원문 JSON 페이지 조회
命令说明
nearby --lat LAT --lon LON [--radius-m 500] [--limit 10] [--json]
查询坐标周边的实时租赁点
search <关键词> [--limit 10] [--json]
搜索名称包含关键词的租赁点实时状态
realtime [--start-index 1 --end-index 1000]
查询实时租赁信息的原始JSON页面

Workflow

Workflow

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

1. 查询当前位置周边的租赁点

bash
python3 "$SKILL_DIR/scripts/seoul_bike.py" nearby --lat 37.5717 --lon 126.9763 --radius-m 500
요약 항목:
  • 대여소명
  • 대여 가능 자전거 수 (
    parkingBikeTotCnt
    )
  • 빈 거치대 수 (
    rackTotCnt - parkingBikeTotCnt
    )
  • 거리(m)
  • 조회 시각(
    proxy.requested_at
    )
bash
python3 "$SKILL_DIR/scripts/seoul_bike.py" nearby --lat 37.5717 --lon 126.9763 --radius-m 500
汇总项：
  • 租赁点名称
  • 可借车辆数 (
    parkingBikeTotCnt
    )
  • 空车位数量 (
    rackTotCnt - parkingBikeTotCnt
    )
  • 距离(米)
  • 查询时间(
    proxy.requested_at
    )

2. 대여소 이름 검색

2. 搜索租赁点名称

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

3. Proxy endpoints

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 주변 대여소 필터링
  • 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
    → 代理端过滤周边租赁点

Done when

Done when

  • 대여 가능 자전거 수와 빈 거치대 수가 정리되어 있다.
  • live data 기준 조회 시각이 명시되어 있다.
  • upstream key가 클라이언트에 노출되지 않았다.
  • 整理好可借车辆数和空车位数量。
  • 明确标注基于实时数据的查询时间。
  • 上游密钥未暴露给客户端。

Failure modes

Failure modes

  • proxy upstream key 미설정 (
    SEOUL_OPEN_API_KEY
    없음)
  • 서울 열린데이터 광장 quota 초과
  • 실시간 API가 빈 행 또는 일시 오류를 반환
  • 좌표가 없거나 반경 안에 대여소가 없음
  • 代理上游密钥未设置（无
    SEOUL_OPEN_API_KEY
    ）
  • 首尔开放数据广场配额超限
  • 实时API返回空结果或临时错误
  • 无坐标或范围内无租赁点

Notes

Notes

  • 실시간 데이터는 계속 변하므로 답변에 조회 시각을 함께 적는다.
  • 예약/대여 자동화는 하지 않는다. 조회 전용 스킬이다.
  • proxy 운영/환경변수 설정은 
    docs/features/k-skill-proxy.md
    를 참고한다.
  • 由于实时数据持续变化，回复中需附带查询时间。
  • 不支持预约/租赁自动化，仅为查询类技能。
  • 代理运维/环境变量设置请参考
    docs/features/k-skill-proxy.md
    。