네이버 지도 API 사용법: Maps 설정부터 지도·마커 표시까지

안녕하세요. 사랑받는 IT 프로덕트의 첫걸음, 똑똑한개발자입니다.

네이버 지도 API는 웹·앱에 지도를 표시하거나 주소·좌표·경로 데이터를 조회하는 기능입니다. 네이버 클라우드 플랫폼의 Maps에서 이용 신청과 인증 정보를 관리합니다. 오늘은 Application 설정부터 지도·마커 표시, 인증 오류 확인까지 알아보겠습니다.

네이버 지도 API, 2025년부터 Maps 상품으로 바뀌었습니다

검색되는 예전 글은 대부분 AI·NAVER API 기준입니다. NCP가 2025년 5월에 올리고 6월에 고친 공지를 보면 2025년 3월 지도 전용 상품 Maps가 따로 출시됐고 2025년 7월 1일부터 AI·NAVER API 안의 지도 API 7종은 무료 이용량 없이 전량 유료로 바뀌었습니다.

구 상품의 지도 API는 점진적으로 종료될 예정입니다. 새로 시작한다면 Maps 상품으로 갑니다. 지도 스타일을 바꾸는 Map Style Editor도 신규 상품에만 있습니다.

네이버 지도 API 사용법, Application 등록부터 합니다

첫 단계는 Maps 이용 신청입니다.

콘솔의 Services > Application Services > Maps에서 Subscription을 열고 [이용 신청]을 누른 뒤 약관에 동의하면 됩니다. 무료 이용량을 넘기면 과금되니 결제 수단도 확인해 둡니다.

Application 등록 때 쓸 API를 체크해야 합니다.

체크하지 않은 API를 부르면 429(Quota Exceed) 오류가 납니다.

Web 서비스 URL 칸에는 호스트만 들어갑니다.

최대 10개까지 등록되며 포트와 경로는 빼야 합니다. 로컬은 http://localhost로 적으면 됩니다. 등록을 마친 뒤 목록의 [인증 정보]를 열면 Client ID와 Client Secret이 보입니다.

네이버 지도 API로 지도와 마커 띄우기

스크립트 파라미터로는 ncpKeyId를 씁니다.

예전 글의 ncpClientId는 변경 전 콘솔의 이름입니다.

<div id="map" style="width:100%;height:400px;"></div>
<script src="https://oapi.map.naver.com/openapi/v3/maps.js?ncpKeyId=CLIENT_ID"></script>
<script>
  var pos = new naver.maps.LatLng(37.3595704, 127.105399);
  var map = new naver.maps.Map('map', { center: pos, zoom: 15 });
  var marker = new naver.maps.Marker({ position: pos, map: map });
  var info = new naver.maps.InfoWindow({ content: '<div>본점</div>' });
  naver.maps.Event.addListener(marker, 'click', function () { info.open(map, marker); });
</script>

지도 영역에 높이가 없으면 빈 화면만 남습니다.

높이가 0이어도 오류가 나지 않으니 꼭 지정합니다. 정보창은 마커 클릭 이벤트로 엽니다.

Geocoding·Reverse Geocoding·Directions는 서버에서 부릅니다

주소를 좌표로 바꾸는 쪽이 Geocoding입니다.

https://maps.apigw.ntruss.com/map-geocode/v2/geocode에 query로 주소를 보내면 x(경도)와 y(위도)가 옵니다. 헤더에는 Client ID와 Client Secret을 싣습니다.

좌표에서 주소를 얻으려면 Reverse Geocoding을 씁니다.

map-reversegeocode/v2/gc에 넣는 coords는 경도,위도 순서입니다.

자동차 경로가 필요하다면 Directions 5입니다.

map-direction/v1/driving에 start와 goal을 넣으면 거리(m)와 소요 시간(ms)이 돌아옵니다. 경유지가 5개를 넘으면 Directions 15를 씁니다.

세 API 모두 Client Secret이 들어가니 브라우저에서 부르면 안 됩니다. CORS 오류도 나서 NCP 문서도 같은 도메인의 백엔드를 두라고 안내합니다.

인증 실패 오류와 무료 이용량

인증에 실패했다면 URL과 파라미터부터 의심해야 합니다.

Web 서비스 URL에 포트나 경로가 붙었는지, 파라미터 이름과 Client ID가 맞는지 봅니다. 실패할 때 호출되는 전역 함수 navermap_authFailure에는 안내 문구를 넣어 둡니다.

무료 이용량이 붙는 계정은 대표 계정 1개뿐입니다.

Maps의 무료 이용량은 API 종류마다 다릅니다. Dynamic Map은 대표 계정 기준 월 600만 건이며, Geocoding과 Directions는 각각의 최신 요금표를 확인합니다. 같은 사업자번호의 계정 중 Maps를 먼저 쓴 계정만 대표 계정이 됩니다. Application이 여럿이어도 무료 이용량은 하나로 세므로 '한도 및 알림 설정'으로 상한을 걸어 둡니다.

카카오맵 vs 네이버 지도, 무엇으로 고를까

지도와 자동차 경로를 함께 사용하는 서비스에서는 Directions 지원 범위와 경유지 조건도 비교할 수 있습니다. 카카오 로그인을 이미 붙인 서비스라면 같은 앱에서 카카오맵만 켜면 됩니다.

운영 계정은 서비스 소유 주체와 담당자를 확인해 관리합니다. 무료 이용량, 결제수단, 한도 알림이 연결되는 계정이므로 운영을 넘길 때도 함께 확인할 항목입니다.

무료 이용량과 대표 계정 조건은 네이버 클라우드 FAQ에서 확인할 수 있습니다. 이미지의 한도 수치는 제작 시점 기준입니다.

세부 항목과 최신 적용 조건은 네이버 Maps Application 가이드를 참고해 보세요.

지도에서 찾은 장소를 서비스 이용으로 연결해요

서비스에 필요한 연동 기능을 하나씩 붙이다 보면 화면뿐 아니라 데이터와 운영 방식도 함께 살펴보게 됩니다. 지금 서비스에 필요한 범위부터 차근차근 정리해볼 수 있습니다.

똑똑한개발자는 UX/UI 디자인과 웹·앱 개발을 함께 진행합니다. 사용자가 이용하는 화면과 운영에 필요한 기능을 연결해 서비스를 만들어가는 과정을 돕습니다.

서비스에 필요한 연동 기능을 준비하면서 궁금한 점이 있다면 아래 똑똑한개발자 링크로 편하게 이야기 남겨주세요. 함께 살펴보겠습니다. 감사합니다. :)