길찾기 3사 비교 (navi-compare)

네이버지도 · 카카오맵 · 티맵의 자동차 길찾기 결과(소요시간, 거리, 통행료, 정체 현황, 주요 도로)를 한 화면에서 비교합니다.

앱	상태	사용 API
카카오맵	연동됨	카카오 Local(장소 검색) + 카카오모빌리티 Directions
네이버지도	샘플 값	(다음 단계) 네이버 클라우드 Maps Directions
티맵	샘플 값	(다음 단계) TMAP 경로안내 API

API 키는 server.js에만 두고, 브라우저는 /api/*만 호출합니다. 키가 화면 코드에 노출되지 않아요.

실행

Node.js 18 이상이 필요합니다. 외부 패키지는 없어요.

cp .env.example .env      # 키 입력
npm start                 # http://localhost:3000
npm test                  # 응답 변환 테스트

카카오 키 발급

1. 카카오 디벨로퍼스 → 내 애플리케이션 → 애플리케이션 추가
2. 앱 설정의 앱 키에서 REST API 키를 복사해 .env의 KAKAO_REST_API_KEY에 넣기
3. 앱의 카카오맵 사용 설정을 활성화 (꺼져 있으면 장소 검색이 OPEN_MAP_AND_LOCAL 권한 오류로 막혀요)

자동차 길찾기는 비상업적 용도라면 기본 무료 쿼터 안에서 별도 제휴 없이 쓸 수 있습니다. 서비스로 운영할 계획이면 카카오모빌리티에 이용 조건을 확인하세요.

동작 방식

• 출발 시각이 현재 ±5분이면 실시간 길찾기(/v1/directions), 그 외에는 미래 시각 길찾기(/v1/future/directions)를 씁니다. 이미 지난 시각을 고르면 다음 날 같은 시각으로 계산해요.
• 카카오 traffic_state는 4 → 원활, 3·2 → 서행, 1·6 → 정체, 0 → 정보 없음으로 묶어 표시합니다.
• 정체 띠는 도로 구간 길이 비율 그대로 그리고, 주요 도로는 같은 이름의 연속 구간을 합친 뒤 긴 순서 상위 6개를 경로 순서대로 보여줍니다.
• 카카오 장소 검색으로 얻은 실제 좌표를 샘플 카드 계산에도 써서, 연동 전 앱도 거리 규모는 비슷하게 맞춰집니다.

지도

각 카드의 경로 지도는 그 앱의 지도 SDK로 그립니다. 불러오지 못하면 OpenStreetMap(Leaflet)으로 대신 그리고, 이유를 카드 아래에 표시해요.

앱	필요한 것
티맵	경로 안내와 같은 appKey (별도 키를 쓰려면 TMAP_MAP_APP_KEY)
네이버지도	네이버 클라우드 콘솔에서 해당 Application에 Dynamic Map 이용 신청, 서비스 URL에 http://localhost:3000 등록 (Client ID 재사용)
카카오맵	JavaScript 키를 .env의 KAKAO_JS_KEY에 넣고, 카카오 디벨로퍼스의 플랫폼 > Web에 http://localhost:3000 등록

지도 SDK는 브라우저에서 불러오므로 해당 키가 화면에 노출돼요. 네이버 Client ID와 카카오 JavaScript 키는 허용 도메인으로 제한해서 쓰는 공개용 키입니다.

유류비

유종(휘발유·경유·전기)과 내 차의 연비를 직접 입력합니다. 단가는 오피넷 전국 평균이며, OPINET_API_KEY가 있으면 6시간마다 갱신하고 없으면 코드의 기본값을 씁니다. 전기 단가는 오피넷 대상이 아니라 참고값이에요.

공유하기 (주소로 다른 사람이 쓰게 할 때)

혼자 내 컴퓨터에서 쓸 때는 아무 설정이 필요 없어요. 서버는 기본으로 127.0.0.1에서만 열려서 같은 와이파이의 다른 기기에서도 접속할 수 없습니다.

가장 안전한 방법은 각자 자기 키로 실행하는 거예요. 저장소를 내려받아 .env에 본인 키를 넣고 npm start. 내 키가 다른 사람에게 갈 일이 없어요.

내 서버 주소를 열어서 쓰게 하려면 아래를 꼭 설정하세요. 설정하지 않으면 주소를 아는 누구나 내 API 쿼터를 쓸 수 있습니다.

설정	설명
APP_PASSWORD	접속 비밀번호. 설정하면 처음 열 때 비밀번호만 입력하는 로그인 화면이 나오고, 맞으면 30일 동안 로그인이 유지돼요. 10번 틀리면 그 IP는 10분간 잠깁니다
HOST=0.0.0.0	배포 서비스에서 외부 접속을 받을 때. 반드시 APP_PASSWORD와 함께 쓰세요
TRUST_PROXY=1	Render·Railway 같은 프록시 뒤에서 접속자별 IP로 제한하려면. 없으면 모든 접속자가 한 IP로 보여 한 명이 틀려도 전원이 잠겨요
DAILY_LIMIT_ROUTE	앱별 길찾기 하루 호출 상한(기본 1500, 카카오 무료 쿼터는 하루 1만 건)
DAILY_LIMIT_SEARCH	장소 검색·자동완성·좌표→주소 하루 상한(기본 3000)
RATE_LIMIT_PER_MIN	접속자 IP당 분당 API 요청 수(기본 120)

• 일일 상한은 한국 시간 자정에 초기화되고, 서버를 다시 켜면 0으로 돌아가요. 한도를 넘으면 "오늘 사용 한도에 도달했어요"라고 안내합니다.
• 배포 주소를 카카오 디벨로퍼스(플랫폼 > Web)와 네이버 클라우드(서비스 URL)에 추가로 등록해야 지도가 떠요.
• HTTPS가 아니면 비밀번호가 평문으로 오가니, 배포 서비스의 HTTPS 주소로 공유하세요.
• 네이버 클라우드 콘솔에서 사용량·결제 알림을 켜 두는 걸 권해요. 네이버는 호출량만큼 과금될 수 있습니다.
• 지도 SDK 때문에 티맵 appKey가 접속자 브라우저에 보여요. 공유 서버라면 지도용 키를 따로 발급해 TMAP_MAP_APP_KEY로 쓰세요.