웹 개발을 공부하면서 “우리 서비스에 지도 기능을 넣고 싶다”는 생각을 해보셨나요? 카카오지도 API는 국내에서 가장 친숙한 지도 서비스를 내 웹사이트에 연동할 수 있는 도구예요. JavaScript에 대한 기초 지식만 있으면 누구나 시작할 수 있고, 공식 문서도 한국어로 잘 정리되어 있어 접근하기 쉽습니다.
이 글에서는 카카오지도 API 사용법을 처음 접하는 분들도 따라할 수 있도록 실제 코드와 함께 단계별로 설명해 드릴게요. API 키 발급부터 지도 표시, 마커 추가, 장소 검색, 현재 위치 표시까지 핵심 기능들을 차례로 알아볼게요.
카카오지도 API 사용 준비
API 키 발급 단계
카카오지도 API를 사용하려면 먼저 카카오 개발자 사이트에서 앱을 등록하고 API 키를 발급받아야 해요. 아래 절차를 따르면 됩니다.
- 1단계: 카카오 개발자 사이트(developers.kakao.com)에 카카오 계정으로 로그인
- 2단계: ‘내 애플리케이션 → 애플리케이션 추가하기’에서 앱 이름과 사업자명 입력 후 저장
- 3단계: 생성된 앱의 ‘앱 키’에서 JavaScript 키 확인 및 복사
- 4단계: ‘플랫폼 → Web → 사이트 도메인 등록’에서 사용할 도메인 주소 등록(예: http://localhost:3000)
이 네 가지 단계를 완료하면 API를 사용할 준비가 끝나요. 도메인 등록을 빠뜨리면 API가 작동하지 않으니 꼭 확인하세요.
기본 HTML 파일 구성
API를 불러올 HTML 파일을 준비해요. head 태그 안에 카카오 지도 SDK를 로드하는 스크립트를 추가하고, body 안에 지도가 표시될 div 요소를 만들면 됩니다. SDK 스크립트의 appkey 파라미터에는 발급받은 JavaScript 키를 입력해야 해요. div 요소의 id는 JavaScript에서 지도를 초기화할 때 참조하는 값이므로 기억하기 쉬운 이름(예: map)으로 지정하세요. CSS에서 해당 div의 width와 height를 지정해야 지도가 화면에 표시됩니다. 높이를 지정하지 않으면 0이 되어 지도가 보이지 않는 흔한 실수를 조심하세요.
지도 초기화 JavaScript 코드
HTML 파일 하단(또는 DOMContentLoaded 이벤트 내)에 지도를 초기화하는 JavaScript 코드를 작성해요. kakao.maps.LatLng 객체로 중심 좌표를 만들고, kakao.maps.Map 생성자에 지도 컨테이너 DOM 요소와 옵션 객체(center, level)를 전달하면 지도가 생성됩니다. level은 줌 레벨로 숫자가 클수록 더 넓은 범위가 보여요. 1이 가장 확대된 상태이고 14가 가장 축소된 상태입니다. 서울 전체를 보려면 level 7~8 정도가 적당해요. 초기 설정을 완료하면 브라우저에서 파일을 열었을 때 카카오맵이 표시되는 것을 확인할 수 있습니다.
지도 기본 조작과 설정
지도 이동과 줌 제어
생성된 지도 객체의 메서드를 사용하면 JavaScript 코드로 지도를 제어할 수 있어요. map.setCenter() 메서드로 지도 중심을 특정 좌표로 이동할 수 있고, map.setLevel() 메서드로 줌 레벨을 변경할 수 있습니다. map.getCenter()와 map.getLevel()로 현재 중심 좌표와 줌 레벨을 가져올 수도 있어요. 버튼 클릭 시 특정 위치로 이동하거나, 리스트에서 항목 선택 시 해당 위치를 지도 중심으로 이동시키는 등 다양한 인터랙션을 구현할 때 활용할 수 있습니다. setBounds() 메서드를 사용하면 여러 좌표를 포함하는 영역 전체가 화면에 표시되도록 지도를 자동 조정할 수도 있어요.
이벤트 리스너 등록
사용자가 지도를 클릭하거나 드래그, 줌 변경 등의 상호작용을 할 때 특정 동작을 실행하고 싶다면 이벤트 리스너를 등록하면 돼요. kakao.maps.event.addListener(map, ‘이벤트명’, 콜백함수) 형태로 사용합니다. 주요 이벤트로는 click(클릭), dblclick(더블클릭), rightclick(우클릭), mousemove(마우스 이동), dragstart(드래그 시작), dragend(드래그 끝), zoom_changed(줌 변경), center_changed(중심 이동) 등이 있어요. 예를 들어 지도를 클릭한 위치에 마커를 추가하거나, 현재 지도 범위에 있는 데이터를 필터링하는 기능을 구현할 때 이벤트를 활용하면 됩니다.
지도 타입과 레이어 변경
map.setMapTypeId() 메서드를 사용하면 지도 유형을 변경할 수 있어요. kakao.maps.MapTypeId.ROADMAP(일반 지도), kakao.maps.MapTypeId.SKYVIEW(스카이뷰/위성), kakao.maps.MapTypeId.HYBRID(일반+스카이뷰 혼합)을 선택할 수 있습니다. 이 외에도 addOverlayMapTypeId() 메서드로 교통 레이어, 지적편집도 레이어, 자전거 도로 레이어 등을 추가로 표시할 수 있어요. 사용자가 버튼을 클릭하여 지도 타입을 전환하는 UI를 구현하면 더 풍부한 사용자 경험을 제공할 수 있습니다.
마커와 인포윈도우 실전 구현
마커 생성과 관리
지도 위에 특정 위치를 표시하는 마커를 추가하려면 kakao.maps.Marker 객체를 생성해요. position(좌표)와 map(마커를 표시할 지도 객체)을 전달하면 바로 지도에 마커가 표시됩니다. 여러 마커를 배열로 관리하면 일괄 처리(숨기기, 제거, 위치 변경 등)가 편리해요. marker.setMap(null)로 마커를 지도에서 숨길 수 있고, marker.setMap(map)으로 다시 표시할 수 있습니다. 마커 드래그 기능을 활성화하려면 draggable: true 옵션을 추가하세요. 사용자가 마커를 드래그한 후 dragend 이벤트에서 변경된 좌표를 처리할 수 있어요.
커스텀 마커 이미지 사용
기본 마커 대신 원하는 이미지로 마커를 표시하려면 kakao.maps.MarkerImage를 사용해요. 이미지 URL, 이미지 크기(kakao.maps.Size), 이미지 오프셋(kakao.maps.Point)을 설정하여 MarkerImage 객체를 만들고, Marker 생성 시 image 옵션으로 전달하면 됩니다. 이미지 오프셋은 마커 이미지의 어느 지점이 지도 좌표와 매핑될지를 지정해요. 보통 마커 이미지 하단 중앙 지점을 좌표와 일치시킵니다. 카테고리별로 다른 색상이나 아이콘의 마커 이미지를 사용하면 여러 유형의 장소를 시각적으로 구분하기 쉬워요.
인포윈도우로 팝업 정보 표시
마커를 클릭했을 때 상세 정보를 팝업으로 보여주려면 kakao.maps.InfoWindow를 사용해요. content 옵션에 HTML 문자열을 전달하여 풍부한 콘텐츠를 표시할 수 있습니다. infowindow.open(map, marker)로 인포윈도우를 열고, infowindow.close()로 닫아요. 마커 클릭 이벤트와 연결하면 마커를 클릭할 때만 인포윈도우가 열리도록 구현할 수 있어요. 여러 마커가 있는 경우 새 마커를 클릭하면 이전 인포윈도우가 닫히도록 처리해야 여러 인포윈도우가 동시에 열리는 것을 방지할 수 있습니다. infowindow.getMap()으로 현재 인포윈도우가 열려 있는지 확인할 수 있어요.
장소 검색 기능 구현하기
키워드 검색 기능 만들기
카카오지도 API의 장소 검색 기능을 사용하려면 SDK 로드 시 libraries=services 파라미터를 추가해야 해요. kakao.maps.services.Places 객체를 생성하고, keywordSearch() 메서드에 검색어와 콜백 함수를 전달하면 됩니다. 검색 결과 콜백에는 results(검색 결과 배열), status(검색 상태), pagination(페이지 정보) 세 가지 인자가 전달돼요. 검색 결과 각 항목에는 place_name(장소 이름), address_name(주소), x(경도), y(위도), phone(전화번호), category_name(카테고리) 등의 정보가 포함되어 있습니다. 이 정보를 활용하여 목록을 화면에 표시하고, 마커를 지도에 추가하는 방식으로 검색 결과를 시각화해요.
주소 검색과 좌표 변환(Geocoding)
사용자가 입력한 주소를 좌표로 변환하는 기능은 많은 서비스에서 필요해요. kakao.maps.services.Geocoder를 사용하면 addressSearch() 메서드로 주소를 좌표로 변환할 수 있습니다. 예를 들어 쇼핑몰 주문 시 배송지 주소를 지도에 마커로 표시하거나, 사용자가 원하는 지역을 입력하면 해당 지역으로 지도를 이동하는 기능을 구현할 때 유용해요. 반대로 coord2Address() 메서드를 사용하면 좌표를 주소로 변환할 수 있습니다. 사용자가 지도를 클릭한 위치의 주소를 알아내거나, GPS 좌표를 읽기 쉬운 주소로 변환할 때 활용해요.
카테고리 검색 기능
현재 지도 화면 범위 내에서 특정 카테고리의 장소를 검색하는 카테고리 검색 기능도 있어요. places.categorySearch(카테고리코드, 콜백, 옵션) 형태로 사용합니다. 카테고리 코드는 음식점(FD6), 카페(CE7), 편의점(CS2), 주유소(OL7), 주차장(PK6), 병원(HP8) 등이 있어요. 옵션으로 location(기준 좌표), radius(반경, 미터), bounds(검색 범위) 등을 지정할 수 있습니다. 지도를 이동할 때마다 center_changed 이벤트를 감지하여 카테고리 검색을 재실행하면, 지도 이동에 따라 현재 화면에 있는 주변 시설 목록이 실시간으로 업데이트되는 기능을 구현할 수 있어요.
현재 위치와 고급 기능
현재 위치 받아와서 지도에 표시
HTML5의 Geolocation API와 카카오지도 API를 함께 사용하면 현재 위치를 지도에 표시하는 기능을 구현할 수 있어요. navigator.geolocation.getCurrentPosition() 함수를 호출하면 콜백으로 위치 정보(위도, 경도)를 받아올 수 있습니다. 받아온 좌표를 kakao.maps.LatLng로 변환하여 지도 중심을 이동하고 마커를 추가하면 현재 위치가 지도에 표시돼요. HTTPS 환경에서만 Geolocation API가 작동하는 경우가 있으니, 개발 서버도 가능하면 HTTPS로 구성하는 것이 좋습니다. 사용자가 위치 권한을 거부하는 경우를 대비한 오류 처리도 꼭 구현해야 해요.
클러스터링으로 다수 마커 관리
마커가 수십 개 이상 되면 지도가 복잡해지는 문제가 생겨요. SDK 로드 시 libraries=clusterer를 추가하면 클러스터링 기능을 사용할 수 있습니다. kakao.maps.MarkerClusterer를 생성하면서 gridSize(클러스터 셀 크기), minLevel(클러스터링 최소 줌 레벨), minClusterSize(클러스터 최소 마커 수), averageCenter(클러스터 중심 평균 여부), styles(클러스터 표시 스타일 배열) 등의 옵션을 설정할 수 있어요. addMarkers() 메서드로 마커 배열을 추가하면 자동으로 클러스터링이 적용됩니다. 지도를 확대하면 클러스터가 풀리고, 축소하면 다시 뭉쳐지는 직관적인 UX가 자동으로 구현돼요.
로드뷰 연동하기
카카오지도 API에는 로드뷰(거리 뷰) 기능도 있어요. kakao.maps.RoadviewClient를 사용하면 특정 좌표에서 가장 가까운 로드뷰 파노라마 ID를 찾을 수 있고, 이를 kakao.maps.Roadview 객체와 연결하면 로드뷰 화면을 표시할 수 있습니다. 지도와 로드뷰를 좌우로 나란히 배치하거나, 마커 클릭 시 로드뷰로 전환하는 등 다양한 UI를 구성할 수 있어요. 부동산 서비스나 관광 안내 서비스에서 특히 유용한 기능이에요. 공식 문서의 로드뷰 관련 샘플 코드를 참고하면 빠르게 구현할 수 있습니다.
카카오지도 API 실전 프로젝트 아이디어
매장 위치 안내 페이지
카카오지도 API를 처음 실습하기에 좋은 프로젝트로 매장 위치 안내 페이지가 있어요. 가게나 회사 홈페이지에 위치 지도를 삽입하고, 주소를 마커와 인포윈도우로 표시하는 간단한 기능으로 시작할 수 있습니다. 오시는 길 안내와 함께 주변 주차장, 가까운 지하철역 등을 함께 표시하면 실용적인 페이지가 돼요. 여러 지점이 있는 경우 지점 목록을 클릭하면 해당 지점으로 지도가 이동하는 기능도 추가해보세요. 이 프로젝트만으로도 지도 초기화, 마커, 인포윈도우, 지도 이동 등 핵심 기능을 모두 연습할 수 있어요.
주변 시설 탐색 서비스
현재 위치 주변의 카페, 음식점, 편의점 등을 카테고리별로 검색하여 지도에 표시하는 서비스를 만들어볼 수 있어요. 이 프로젝트에서는 Geolocation API, 카테고리 검색, 마커 클러스터링 등을 종합적으로 활용할 수 있습니다. 검색 결과를 목록과 지도를 함께 표시하고, 목록 항목 클릭 시 해당 마커가 강조 표시되도록 구현하면 완성도 높은 서비스가 돼요. 이 정도 프로젝트를 완성하면 카카오지도 API의 주요 기능을 대부분 다루게 됩니다.
여행 코스 공유 서비스
여러 장소를 순서대로 연결하여 여행 코스를 지도에 표시하는 서비스도 좋은 실습 프로젝트예요. 장소 목록을 입력하면 각 장소에 마커를 표시하고, 마커들을 순서대로 선(polyline)으로 연결하는 기능을 구현할 수 있습니다. kakao.maps.Polyline을 사용하면 지도 위에 선을 그릴 수 있어요. 코스를 URL로 공유하거나, 코스 데이터를 JSON으로 저장하고 불러오는 기능도 추가하면 완성도 있는 서비스가 됩니다. 카카오지도 API의 폴리라인, 폴리곤 등 오버레이 기능을 연습하기에도 좋은 프로젝트예요.
마치며
카카오지도 API는 국내 서비스에 최적화된 풍부한 기능을 갖추고 있어요. 이 글에서 다룬 API 키 발급, 지도 초기화, 마커와 인포윈도우, 장소 검색을 잘 익혀두면 다양한 서비스에 지도 기능을 손쉽게 추가할 수 있습니다.
처음에는 공식 문서의 샘플 코드를 그대로 실행해보면서 동작을 이해하고, 조금씩 변형해가며 나만의 기능으로 발전시키는 방식을 추천해요. 카카오 개발자 사이트의 Kakao Maps API 가이드와 샘플 페이지(apis.map.kakao.com)를 즐겨찾기해두고 필요할 때마다 참고하세요.