naver-map-route

Naver Map Route (네이버 지도 길찾기 MVP)

⚠️ Currently not working (2026-05-25): The NCP Maps operator key is not yet configured on the proxy server, so live mode does not work. Only mock fallback is available. This notice will be removed once the key is configured after completing NCP payment method registration.

What this skill does

When the user /route or /이동루트 enters the origin and destination directly with the command, NAVER Cloud Platform Maps Directions 5 queries the result via k-skill-proxy and summarizes distance, travel time, tolls, and fuel cost.

• The operator keeps the NCP Maps key only on the proxy server side, and users do not need a separate key.
• The default mode is mock. Only when explicitly enabled (ROUTE_PLANNER_ENABLE_LIVE_PROVIDER=true + ROUTE_PLANNER_PROVIDER=naver) does it perform a live proxy call.
• On missing key or authentication failure, it gracefully falls back to providing mock results.

MVP acceptance criteria for issue #268:

• /route Manual input responds correctly
• /이동루트 Manual input responds correctly
• Stable operation in default mock mode
• Selects naver provider when live is explicitly enabled + key exists
• Fallback response on missing/failed key
• Does not expose secret/token/.env raw contents

When to use

• One-line manual input such as "/route Gangnam Station to City Hall Station"
• "/이동루트 출발: <주소> / 도착: <주소>"
• "How long does it take by car from Gangnam Station to City Hall?" (converted to manual coordinate/address input, then directions)
• Car-based route summary, check distance, travel time, tolls, and fuel cost

When NOT to use

• Walking, bicycle, and public transit routes (public transit uses the existing korean-transit-route skill, walking and bicycle use separate skills)
• A task that tracks real-time traffic changes on a 1-minute basis (proxy cache exists)
• Automatic current location detection / calendar integration (outside MVP scope)

Prerequisites

• Uses only the Python 3 standard library (urllib, argparse, json).
• optional: KSKILL_PROXY_BASE_URL (set only when using self-host/separate proxy. If empty, the default hosted https://k-skill-proxy.nomadamas.org).
• optional: ROUTE_PLANNER_PROVIDER=naver (only when the value is naveris it a live provider candidate).
• optional: ROUTE_PLANNER_ENABLE_LIVE_PROVIDER=true (explicitly allows live calls).

Required environment variables

On the user's machine, is not needed. The operator places the following on the proxy server side:

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

If the proxy server runs without this key, /v1/naver-map/* the route returns 503 upstream_not_configured . The client uses this as a mock fallback signal.

Decision flow

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"

Proxy routes

endpoint	upstream	Main input
GET /v1/naver-map/directions	NCP Maps Directions 5 (/map-direction/v1/driving)	start=lng,lat, goal=lng,lat, waypoints (up to 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

Workflow

1. Organize user input

• /route <start>, <goal> or /이동루트 출발: <start> 도착: <goal> pattern.
• Coordinates (126.9706,37.5559) or address (강남역 1번 출구) are both allowed. For an address, coordinates are obtained through the geocode step.

2. mock mode (default)

ROUTE_PLANNER_ENABLE_LIVE_PROVIDER is empty or trueis not, it immediately creates a mock result:

{
  "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 mode

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'

In the response, read the default option=trafast criterion route.trafast[0].summary , and if another option is specified, route[option][0].summary map to the following:

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

4. Address → coordinate conversion (only when needed)

When the user does not know the coordinates and provides only an address:

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

In the response, addresses[0].x (lng), addresses[0].y (lat) is used.

5. Output format

[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

Failure modes

• proxy upstream key not set (NAVER_MAP_CLIENT_ID/SECRET none) → 503 upstream_not_configured → mock fallback
• NCP Maps authentication failure (401/403) → proxy converts to 503 → mock fallback
• NCP Maps quota/rate-limit (429) → proxy가 429 upstream_error is preserved → mock fallback + retry interval guidance
• Route not found (code != 0) → 502 upstream_semantic_error → guide with a message
• Invalid coordinate format → 400 bad_request
• Network failure → 502 upstream_error → mock fallback

Done when

• The user /route or /이동루트 When the origin and destination are given, one result is clearly returned, either mock or live.
• The live response contains organized distance/time/toll/fuel cost/query time.
• The raw secret/token/.env text is never exposed in the response.
• When live fails, the mock fallback works, and it is stated to the user that it is a fallback.

Notes

• 본 MVP는 Car routesis limited to. For walking, bicycling, and public transit, use separate skills.
• waypoints max 5 (NCP Maps policy).
• option=trafast(fastest route) is the default. For the exact definition, refer to the official NCP Maps Directions 5 documentation.
• For proxy operations/environment variable settings, refer to docs/features/k-skill-proxy.md .
• Automatic current location detection and calendar reading are intentionally excluded from scope (issue #268 OUT).