naver-map-route

Naver Map Route（네이버 지도 길찾기 MVP）

⚠️ 現在は未動作（2026-05-25）：NCP Maps の運営者キーがプロキシサーバーにまだ設定されていないため、live モードは動作しません。mock fallback のみ利用できます。NCP の支払い方法の登録完了後にキーを設定したら、この案内を削除します。

このスキルでできること

ユーザーが /route または /이동루트 コマンドで出発地・目的地を直接入力すると、NAVER Cloud Platform Maps Directions 5 の結果を k-skill-proxy 経由で取得し、距離・所要時間・通行料金・燃料費を要約します。

• 運営者が NCP Maps のキーをプロキシサーバー側だけに保管するため、ユーザーは別途キーを用意する必要はありません。
• デフォルトのモードは mock です。明示的に有効化（ROUTE_PLANNER_ENABLE_LIVE_PROVIDER=true + ROUTE_PLANNER_PROVIDER=naver）した場合のみ、live proxy 呼び出しを実行します。
• キーの不足・認証失敗時は graceful fallback として mock の結果を案内します。

イシュー #268 の MVP 受け入れ基準：

• /route の手動入力に正常に応答する
• /이동루트 の手動入力に正常に応答する
• デフォルトの mock モードで安定して動作する
• live を明示的に有効化し、キーが存在する場合に naver provider が選択される
• キーの不足・失敗時に fallback で応答する
• secret/token/.env の内容を漏えいしない

使用する場合

• 「/route 江南駅から市庁駅」のような1行の手動入力
• 「/이동루트 出発地: <住所> / 到着地: <住所>」
• 「江南駅から市庁まで車でどのくらいかかる？」（手動での座標・住所入力に変換してからルート検索）
• 自動車でのルートの要約、距離・所要時間・通行料金・燃料費の確認

使用しない場合

• 徒歩・自転車・公共交通機関のルート（公共交通機関には既存の korean-transit-route スキル、徒歩・自転車には別のスキルを使用）
• リアルタイムの交通状況の変化を1分単位で追跡する作業（proxy cache があります）
• 現在地の自動認識／カレンダー連携（MVP の対象外）

前提条件

• Python 3 の標準ライブラリのみを使用します（urllib、argparse、json）。
• 任意：KSKILL_PROXY_BASE_URL（セルフホストや別のプロキシを使用する場合のみ設定します。空欄の場合はデフォルトの hosted https://k-skill-proxy.nomadamas.org を使用します）。
• 任意：ROUTE_PLANNER_PROVIDER=naver（値が naver の場合のみ、live provider の候補になります）。
• 任意：ROUTE_PLANNER_ENABLE_LIVE_PROVIDER=true（live 呼び出しを明示的に許可します）。

必須の環境変数

ユーザーのマシンには不要です。 運営者がプロキシサーバー側に次の値を設定します。

• NAVER_MAP_CLIENT_ID — NCP Maps subaccount client id
• NAVER_MAP_CLIENT_SECRET — NCP Maps subaccount client secret

プロキシサーバーがこれらのキーなしで起動した場合、/v1/naver-map/* ルートは 503 upstream_not_configured を返します。クライアントはこれを mock fallback のシグナルとして使用します。

判定フロー

provider 결정
├── ROUTE_PLANNER_ENABLE_LIVE_PROVIDER != "true"
│     → mock 결과 반환
├── ROUTE_PLANNER_PROVIDER != "naver"
│     → mock 결과 반환
└── live 시도
      ├── proxy /v1/naver-map/directions 호출
      ├── 503 / 502 / 네트워크 실패
      │     → mock fallback + warning 메모
      └── 정상 응답
            → 요약 + provider="naver"

プロキシルート

endpoint	upstream	主な入力
GET /v1/naver-map/directions	NCP Maps Directions 5（/map-direction/v1/driving）	start=lng,lat、goal=lng,lat、waypoints（最大5）、option=trafast|tracomfort|traoptimal|traavoidtoll|traavoidcaronly、lang=ko
GET /v1/naver-map/geocode	NCP Maps Geocoding（/map-geocode/v2/geocode）	q、coordinate、filter、language、page、count
GET /v1/naver-map/reverse-geocode	NCP Maps Reverse Geocoding（/map-reversegeocode/v2/gc）	coords=lng,lat、orders=roadaddr,addr,legalcode,admcode、output=json

ワークフロー

1. ユーザー入力の整理

• /route <start>, <goal> または /이동루트 出発地: <start> 到着地: <goal> のパターンを受け取ります。
• 座標（126.9706,37.5559）と住所（江南駅1番出口）のどちらも使用できます。住所の場合は、geocode の段階で座標を取得します。

2. mock モード（デフォルト）

ROUTE_PLANNER_ENABLE_LIVE_PROVIDER が空欄、または true でない場合は、ただちに mock の結果を作成します。

{
  "provider": "mock",
  "start": { "label": "강남역", "lng": null, "lat": null },
  "goal": { "label": "시청역", "lng": null, "lat": null },
  "summary": {
    "distance_km": null,
    "duration_minutes": null,
    "toll_won": null,
    "fuel_won": null
  },
  "note": "live provider is disabled. Set ROUTE_PLANNER_PROVIDER=naver and ROUTE_PLANNER_ENABLE_LIVE_PROVIDER=true to call the proxy."
}

3. live モード

ROUTE_PLANNER_PROVIDER=naver + ROUTE_PLANNER_ENABLE_LIVE_PROVIDER=true：

BASE="${KSKILL_PROXY_BASE_URL:-https://k-skill-proxy.nomadamas.org}"
curl -fsS --get "${BASE}/v1/naver-map/directions" \
  --data-urlencode 'start=126.9706,37.5559' \
  --data-urlencode 'goal=127.0276,37.4979' \
  --data-urlencode 'option=trafast'

応答からデフォルトの option=trafast に対応する route.trafast[0].summary を読み取り、別の option が明示されている場合は route[option][0].summary を次のようにマッピングします。

• distance（meter）→ distance_km = distance / 1000
• duration（millisecond）→ duration_minutes = duration / 60000
• tollFare → toll_won
• fuelPrice → fuel_won

4. 住所から座標への変換（必要な場合のみ）

ユーザーが座標を知らず、住所だけを指定した場合：

curl -fsS --get "${BASE}/v1/naver-map/geocode" \
  --data-urlencode 'q=강남역 1번 출구' \
  --data-urlencode 'count=1'

応答の addresses[0].x（lng）、addresses[0].y（lat）を使用します。

5. 出力形式

[mock 모드]
경로 요약 (mock): 강남역 → 시청역
- 거리/소요시간/통행료 정보 없음
- live 활성화 방법: ROUTE_PLANNER_PROVIDER=naver, ROUTE_PLANNER_ENABLE_LIVE_PROVIDER=true

[live 모드]
경로 요약 (naver): 강남역(126.9706,37.5559) → 시청역(127.0276,37.4979)
- 거리: 12.3km
- 예상 소요시간: 25분
- 통행료: 1,200원
- 연료비: 1,500원
- 옵션: trafast
- 조회 시각: 2026-05-23T14:00:00.000Z

失敗時の動作

• プロキシの upstream キーが未設定（NAVER_MAP_CLIENT_ID/SECRET なし）→ 503 upstream_not_configured → mock fallback
• NCP Maps の認証失敗（401/403）→ プロキシが 503 に変換 → mock fallback
• NCP Maps の quota/rate-limit（429）→ プロキシが 429 upstream_error を維持 → mock fallback + 再試行間隔を案内
• ルートが見つからない（code != 0）→ 502 upstream_semantic_error → メッセージとともに案内
• 座標形式のエラー → 400 bad_request
• ネットワーク障害 → 502 upstream_error → mock fallback

完了条件

• ユーザーが /route または /이동루트 で出発地・目的地を指定したとき、mock または live の結果のいずれかを明確に返します。
• live の応答では、距離・時間・通行料金・燃料費・照会時刻が整理されています。
• secret/token/.env の内容は応答に絶対に表示されません。
• live の失敗時に mock fallback が動作し、fallback であることがユーザーに明示されます。

Notes

• 본 MVP는 자동차 경로에 한정한다. 도보·자전거·대중교통은 별도 스킬을 사용한다.
• waypoints 는 최대 5개 (NCP Maps 정책).
• option=trafast(빠른 경로) 가 기본. 정확한 정의는 NCP Maps Directions 5 공식 문서를 참고.
• proxy 운영/환경변수 설정은 docs/features/k-skill-proxy.md 를 참고한다.
• 현재 위치 자동 인식·캘린더 읽기는 의도적으로 범위에서 제외된다(이슈 #268 OUT).