naver-map-route

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

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

Naver Map Route（NAVER地图路线规划MVP）

⚠️ 현재 미작동 (2026-05-25): NCP Maps 운영자 키가 프록시 서버에 아직 설정되지 않아 live 모드가 동작하지 않습니다. mock fallback만 사용 가능합니다. NCP 결제수단 등록 완료 후 키를 설정하면 이 안내를 제거합니다.

⚠️ 当前无法运行（2026-05-25）：由于代理服务器尚未配置NCP Maps运营密钥，live模式无法正常工作。目前仅可使用mock fallback。完成NCP支付方式注册并配置密钥后，将移除本提示。

What this skill does

本Skill功能说明

사용자가

/route

또는

/이동루트

명령으로 출발지·목적지를 직접 입력하면, NAVER Cloud Platform Maps Directions 5 결과를

k-skill-proxy

경유로 조회하여 거리·소요 시간·통행료·연료비를 요약한다.

운영자가 NCP Maps key를 proxy 서버 쪽에만 보관하고, 사용자는 별도 key가 필요하지 않다.
기본 모드는 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

或

/이동루트

命令手动输入出发地和目的地时，将通过

k-skill-proxy

调用NAVER Cloud Platform Maps Directions 5接口，返回距离、耗时、通行费、燃油费的汇总信息。

运营方仅需在代理服务器端保存NCP Maps密钥，用户无需单独持有密钥。
默认模式为mock。仅当明确启用（
```
ROUTE_PLANNER_ENABLE_LIVE_PROVIDER=true
```
+
```
ROUTE_PLANNER_PROVIDER=naver
```
）时，才会调用live代理。
若出现密钥缺失、认证失败等情况，将自动降级为mock结果并提示用户。

符合Issue #268的MVP验收标准：

```
/route
```
手动输入可正常响应
```
/이동루트
```
手动输入可正常响应
默认mock模式下稳定运行
明确启用live模式且密钥存在时，选择naver作为数据源
密钥缺失/认证失败时自动降级为mock结果
不暴露secret/token/.env原始信息

When to use

使用场景

"/route 강남역에서 시청역" 같은 한 줄 수동 입력
"/이동루트 출발: <주소> / 도착: <주소>"
"강남역에서 시청까지 차로 얼마나 걸려?" (수동 좌표/주소 입력으로 변환 후 길찾기)
자동차 기준 경로 요약, 거리·소요 시간·통행료·연료비 확인

输入类似"/route 강남역에서 시청역"的单行手动指令
输入"/이동루트 출발: <주소> / 도착: <주소>"
查询类似"강남역에서 시청까지 차로 얼마나 걸려?"的问题（转换为手动坐标/地址输入后进行路线规划）
需要获取驾车路线汇总信息，包括距离、耗时、通行费、燃油费

When NOT to use

非适用场景

도보·자전거·대중교통 경로 (대중교통은 기존
```
korean-transit-route
```
스킬, 도보·자전거는 별도 스킬)
실시간 교통 변동을 1분 단위로 추적하는 작업 (proxy cache가 있음)
현재 위치 자동 인식 / 캘린더 연동 (MVP 범위 밖)

步行/自行车/公共交通路线（公共交通请使用现有
```
korean-transit-route
```
Skill，步行/自行车需使用单独Skill）
需要以分钟为单位追踪实时交通变动的场景（代理存在缓存机制）
自动识别当前位置/联动日历（超出MVP范围）

Prerequisites

前置条件

Python 3 표준 라이브러리만 사용한다 (
```
urllib
```
,
```
argparse
```
,
```
json
```
).
optional:
```
KSKILL_PROXY_BASE_URL
```
(self-host·별도 프록시를 쓸 때만 설정. 비우면 기본 hosted
```
https://k-skill-proxy.nomadamas.org
```
).
optional:
```
ROUTE_PLANNER_PROVIDER=naver
```
(값이
```
naver
```
일 때만 live provider 후보).
optional:
```
ROUTE_PLANNER_ENABLE_LIVE_PROVIDER=true
```
(live 호출을 명시 허용).

仅使用Python 3标准库（
```
urllib
```
,
```
argparse
```
,
```
json
```
）。
可选配置：
```
KSKILL_PROXY_BASE_URL
```
（仅在自托管/使用独立代理时配置，留空则使用默认托管地址
```
https://k-skill-proxy.nomadamas.org
```
）。
可选配置：
```
ROUTE_PLANNER_PROVIDER=naver
```
（仅当值为
```
naver
```
时，才会将其作为live数据源候选）。
可选配置：
```
ROUTE_PLANNER_ENABLE_LIVE_PROVIDER=true
```
（明确允许调用live接口）。

Required environment variables

所需环境变量

사용자 머신에는 필요 없다. 운영자가 proxy 서버 쪽에 다음을 둔다:

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

proxy 서버가 이 키 없이 가동되면

/v1/naver-map/*

라우트는

503 upstream_not_configured

를 돌려준다. 클라이언트는 이를 mock fallback 신호로 사용한다.

用户机器无需配置。运营方需在代理服务器端配置以下变量：

```
NAVER_MAP_CLIENT_ID
```
— NCP Maps子账号client id
```
NAVER_MAP_CLIENT_SECRET
```
— NCP Maps子账号client secret

若代理服务器未配置上述密钥，

/v1/naver-map/*

路由将返回

503 upstream_not_configured

，客户端会将此作为触发mock fallback的信号。

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"

数据源决策
├── ROUTE_PLANNER_ENABLE_LIVE_PROVIDER != "true"
│     → 返回mock结果
├── ROUTE_PLANNER_PROVIDER != "naver"
│     → 返回mock结果
└── 尝试调用live接口
      ├── 调用proxy /v1/naver-map/directions接口
      ├── 出现503 / 502 / 网络失败
      │     → 触发mock fallback并显示警告信息
      └── 响应正常
            → 返回汇总信息 + provider="naver"

Proxy routes

代理路由

endpoint upstream 주요 입력

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`

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

)

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

端点上游服务主要输入参数

端点	上游服务	主要输入参数
`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`

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

)

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. 사용자 입력 정리

1. 整理用户输入

/route <start>, <goal>

또는

/이동루트 출발: <start> 도착: <goal>

패턴을 받는다.

좌표(
```
126.9706,37.5559
```
) 또는 주소(
```
강남역 1번 출구
```
) 둘 다 허용. 주소는 geocode 단계로 좌표를 얻는다.

接收

/route <start>, <goal>

或

/이동루트 출발: <start> 도착: <goal>

格式的指令。

支持坐标（
```
126.9706,37.5559
```
）或地址（
```
강남역 1번 출구
```
）两种输入方式。若为地址，将通过地理编码转换为坐标。

2. mock 모드 (기본)

2. mock模式（默认）

ROUTE_PLANNER_ENABLE_LIVE_PROVIDER

가 비어 있거나

true

가 아니면 즉시 mock 결과를 만든다:

json

{
  "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."
}

若

ROUTE_PLANNER_ENABLE_LIVE_PROVIDER

为空或不等于

true

，将直接生成mock结果：

json

{
  "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 모드

3. live模式

ROUTE_PLANNER_PROVIDER=naver

ROUTE_PLANNER_ENABLE_LIVE_PROVIDER=true

bash

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
```

当

ROUTE_PLANNER_PROVIDER=naver

ROUTE_PLANNER_ENABLE_LIVE_PROVIDER=true

时：

bash

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
```
（米）→
```
distance_km = distance / 1000
```

duration

（毫秒）→

duration_minutes = duration / 60000

```
tollFare
```
→
```
toll_won
```
```
fuelPrice
```
→
```
fuel_won
```

4. 주소 → 좌표 변환 (필요할 때만)

4. 地址→坐标转换（按需执行）

사용자가 좌표를 모르고 주소만 줬을 때:

bash

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

응답의

addresses[0].x

(lng),

addresses[0].y

(lat) 를 사용한다.

当用户仅输入地址而未提供坐标时：

bash

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

使用响应中的

addresses[0].x

（经度）和

addresses[0].y

（纬度）。

5. 출력 포맷

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

[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 미설정 (
```
NAVER_MAP_CLIENT_ID/SECRET
```
없음) →
```
503 upstream_not_configured
```
→ mock fallback
NCP Maps 인증 실패 (401/403) → proxy가
```
503
```
으로 변환 → mock fallback
NCP Maps quota/rate-limit (
```
429
```
) → proxy가
```
429 upstream_error
```
로 보존 → mock fallback + 재시도 간격 안내
경로 미발견 (
```
code != 0
```
) →
```
502 upstream_semantic_error
```
→ 메시지와 함께 안내
좌표 형식 오류 →
```
400 bad_request
```
네트워크 실패 →
```
502 upstream_error
```
→ mock fallback

代理上游未配置密钥（无
```
NAVER_MAP_CLIENT_ID/SECRET
```
）→ 返回
```
503 upstream_not_configured
```
→ 触发mock fallback
NCP Maps认证失败（401/403）→ 代理转换为
```
503
```
→ 触发mock fallback
NCP Maps配额/速率限制（
```
429
```
）→ 代理保留
```
429 upstream_error
```
→ 触发mock fallback并提示重试间隔
未找到路线（
```
code != 0
```
）→ 返回
```
502 upstream_semantic_error
```
→ 显示错误信息
坐标格式错误 → 返回
```
400 bad_request
```
网络失败 → 返回
```
502 upstream_error
```
→ 触发mock fallback

Done when

完成标准

사용자가
```
/route
```
또는
```
/이동루트
```
로 출발지·목적지를 줬을 때, mock 또는 live 결과로 한 가지가 명확히 응답된다.
live 응답에는 거리/시간/통행료/연료비/조회 시각이 정리되어 있다.
secret/token/.env 원문은 응답에 절대 노출되지 않는다.
live 실패 시 mock fallback 이 작동하고, 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).

本MVP仅支持驾车路线。步行/自行车/公共交通需使用单独Skill。
waypoints最多支持5个（NCP Maps政策限制）。
默认选项为
```
trafast
```
（最快路线），具体定义请参考NCP Maps Directions 5官方文档。
代理运营/环境变量配置请参考
```
docs/features/k-skill-proxy.md
```
。
自动识别当前位置/读取日历功能已特意排除在范围外（Issue #268 OUT）。