mirror of https://github.com/NomaDamas/k-skill.git synced 2026-06-24 02:04:11 +00:00

Jeffrey (Dongkyu) Kim 49bf262bb9 Route shared key APIs through the proxy

Move KOSIS general lookups and Kakao Local geocoding behind k-skill-proxy so users do not need to manage those API keys for common skill flows. Keep KOSIS bigdata/direct calls user-keyed because userStatsId is account-specific.

Constraint: Free API proxy policy allows proxying upstreams that require API keys while keeping routes narrow, cache-backed, and public.

Rejected: Proxy ODsay transit routing | Basic quota is low, time-limited, and IP-whitelist-bound, so centralizing it would create quota and operations risk.

Confidence: high

Scope-risk: moderate

Directive: Keep KOSIS bigdata direct unless a per-user credential design is added; do not route broad Kakao surfaces without explicit allowlists and rate limits.

Tested: npm run ci; local KOSIS proxy smoke via /v1/kosis/search and /v1/kosis/meta; local Kakao proxy smoke via /v1/kakao-local/geocode q=서울역.

Not-tested: Production proxy deployment after main merge/cron update.

2026-05-13 16:31:29 +09:00

3.3 KiB

Raw Permalink Blame History

한국 대중교통 길찾기 가이드

이 기능으로 할 수 있는 일

출발지→도착지 도어투도어 대중교통 경로 조회 (지하철 + 버스 + 도보)
ODsay LIVE API 기반 환승 정보, 소요시간, 요금 확인
Kakao Local geocoding으로 주소·장소명→좌표 변환
추천순 / 최소시간 / 최소환승 옵션 선택

먼저 필요한 것

공통 설정 가이드 완료
보안/시크릿 정책 확인
ODsay Server API Key 발급 및 호출 IP 화이트리스트 등록: https://lab.odsay.com
Kakao Local geocoding은 기본 hosted k-skill-proxy 경유. 사용자 쪽 Kakao 키는 불필요하며, self-host proxy 운영자만 Kakao REST API Key를 발급해 서버에 설정한다: https://developers.kakao.com

필요한 환경변수

ODSAY_API_KEY — ODsay LIVE API Server 키

ODSAY_API_KEY 를 ~/.config/k-skill/secrets.env 에 저장하거나 환경변수로 주입한다. 별도 self-host proxy를 쓰는 경우에만 KSKILL_PROXY_BASE_URL 을 설정한다.

입력값

출발지 (주소, 장소명, 또는 좌표)
도착지 (주소, 장소명, 또는 좌표)
선택 사항: 경로 옵션 (OPT=0 추천순, 4 최소시간, 5 최소환승), SearchPathType (0 지하철+버스, 1 지하철만, 2 버스만)

기본 흐름

출발지/도착지를 k-skill-proxy의 /v1/kakao-local/geocode로 geocoding하여 좌표를 확보한다. Proxy 내부에서 Kakao Local address.json → keyword.json 순서로 시도한다.
ODsay searchPubTransPathT에 출발/도착 좌표와 옵션을 전달한다.
응답의 result.path[]를 3개 이내로 정리한다.
각 경로의 subPath[]를 trafficType별로 표시하며, 첫/끝 도보 구간을 반드시 포함한다.

예시

좌표 직접 입력

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=126.9706&SY=37.5559&EX=127.0276&EY=37.4979&OPT=0&SearchPathType=0"

주소→좌표→경로 (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

sx, sy, s_name = geocode('서울역')
ex, ey, e_name = geocode('강남역')
# 이후 ODsay searchPubTransPathT 호출

주의할 점

ODsay Server 키는 호출 IP 화이트리스트 등록이 필수이다. 등록되지 않은 IP에서는 error 응답이 반환된다.
현재 ODsay 공식 Basic 상품 기준 무료 체험은 일 1,000건(6개월)이다. searchPubTransPathT와 searchStation 호출이 합산된다.
한국 외 좌표는 지원하지 않는다.
카카오맵/네이버지도 directions API는 대중교통 라우팅을 공개하지 않으므로 사용하지 말 것.

3.3 KiB Raw Permalink Blame History