mirror of
https://github.com/NomaDamas/k-skill.git
synced 2026-09-14 16:37:18 +08:00
Jeffrey (Dongkyu) Kim
49bf262bb9
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.
73 lines
3.3 KiB
Markdown
73 lines
3.3 KiB
Markdown
# 한국 대중교통 길찾기 가이드
|
|
|
|
## 이 기능으로 할 수 있는 일
|
|
|
|
- 출발지→도착지 도어투도어 대중교통 경로 조회 (지하철 + 버스 + 도보)
|
|
- ODsay LIVE API 기반 환승 정보, 소요시간, 요금 확인
|
|
- Kakao Local geocoding으로 주소·장소명→좌표 변환
|
|
- 추천순 / 최소시간 / 최소환승 옵션 선택
|
|
|
|
## 먼저 필요한 것
|
|
|
|
- [공통 설정 가이드](../setup.md) 완료
|
|
- [보안/시크릿 정책](../security-and-secrets.md) 확인
|
|
- 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` 버스만)
|
|
|
|
## 기본 흐름
|
|
|
|
1. 출발지/도착지를 `k-skill-proxy`의 `/v1/kakao-local/geocode`로 geocoding하여 좌표를 확보한다. Proxy 내부에서 Kakao Local `address.json` → `keyword.json` 순서로 시도한다.
|
|
2. ODsay `searchPubTransPathT`에 출발/도착 좌표와 옵션을 전달한다.
|
|
3. 응답의 `result.path[]`를 3개 이내로 정리한다.
|
|
4. 각 경로의 `subPath[]`를 `trafficType`별로 표시하며, 첫/끝 도보 구간을 반드시 포함한다.
|
|
|
|
## 예시
|
|
|
|
### 좌표 직접 입력
|
|
|
|
```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=126.9706&SY=37.5559&EX=127.0276&EY=37.4979&OPT=0&SearchPathType=0"
|
|
```
|
|
|
|
### 주소→좌표→경로 (Python)
|
|
|
|
```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는 대중교통 라우팅을 공개하지 않으므로 사용하지 말 것.
|