카카오맵 API 지도 검색 완벽 가이드 — 키워드·좌표·장소 검색까지

by

웹사이트나 앱에 지도 기능을 추가하고 싶은데 어디서부터 시작해야 할지 막막하셨나요? 카카오맵 API는 국내 개발자들 사이에서 가장 많이 활용되는 지도 플랫폼 중 하나예요. 구글 지도보다 국내 도로와 건물 정보가 정확하고, 한국어 검색도 훨씬 잘 되거든요.

이 글에서는 카카오맵 API의 지도 검색 기능을 처음부터 차근차근 구현하는 방법을 알아볼게요. 키 발급부터 키워드 검색, 카테고리 검색, 좌표 변환까지 실제로 동작하는 코드와 함께 설명드릴게요.

카카오 개발자 계정과 앱 키 발급받기

개발자 계정 만들기

카카오맵 API를 사용하려면 먼저 Kakao Developers(developers.kakao.com)에 접속해서 개발자 계정을 만들어야 해요. 카카오 계정이 있다면 바로 로그인해서 등록할 수 있어요. 개발자 등록은 무료이고, 개인 정보와 이용 약관 동의만 하면 금방 완료돼요.

앱 등록 및 API 키 확인

개발자 계정 생성 후 ‘애플리케이션 추가하기’를 클릭해서 새 앱을 등록해요. 앱 이름과 사업자명을 입력하면 되는데, 개인 프로젝트라면 본인 이름을 사업자명으로 써도 괜찮아요. 앱을 만들면 네 가지 키가 생성되는데, 지도 API에는 JavaScript 키가 필요해요. 웹 환경에서 주로 사용하고, 웹페이지에 스크립트를 삽입할 때 이 키를 사용해요.

도메인 등록

보안을 위해 반드시 플랫폼 설정에서 사용할 도메인을 등록해야 해요. 로컬 개발 중이라면 http://localhost:3000 같은 형태로 등록하면 돼요. 도메인 등록이 없으면 API 호출 시 CORS 오류가 발생하니 꼭 확인해 주세요.

지도 기본 초기화와 표시

HTML에 스크립트 삽입

카카오맵 API를 사용하려면 HTML 파일의 <head> 태그 안에 아래 스크립트를 삽입해요.

  • <script type="text/javascript" src="//dapi.kakao.com/v2/maps/sdk.js?appkey=발급받은키"></script>
  • 지도 SDK와 함께 검색 라이브러리도 필요하면 &libraries=services를 뒤에 붙여줘요
  • 비동기 로딩이 필요하면 autoload=false 파라미터를 추가할 수 있어요

지도 컨테이너 만들기

지도가 표시될 <div> 요소를 HTML에 추가하고, CSS로 가로·세로 크기를 지정해야 해요. 크기가 지정되지 않으면 지도가 화면에 보이지 않는 문제가 자주 발생하니 주의하세요. 예를 들어 width: 100%; height: 500px;처럼 설정하면 반응형으로도 잘 동작해요.

지도 객체 생성 코드

자바스크립트로 지도를 초기화할 때는 kakao.maps.Map 생성자를 사용해요. 컨테이너 요소와 옵션 객체(중심 좌표, 레벨)를 넘겨주면 돼요. 중심 좌표는 kakao.maps.LatLng(위도, 경도)로 지정하고, 레벨은 1(가장 상세)에서 14(광역)까지 설정할 수 있어요.

키워드로 장소 검색하기

Services 라이브러리 불러오기

키워드 검색을 사용하려면 SDK 로드 시 libraries=services를 포함해야 해요. 이 라이브러리 안에 kakao.maps.services.Places 클래스가 포함돼 있어요. 검색 객체를 하나 생성해두고 여러 번 재사용할 수 있어요.

keywordSearch 메서드 사용법

ps.keywordSearch('검색어', callback) 형태로 간단하게 검색을 실행할 수 있어요. 콜백 함수에는 결과 배열, 상태, 페이지 정보가 전달돼요. 상태가 kakao.maps.services.Status.OK이면 정상 결과가 온 것이고, ZERO_RESULT면 결과가 없는 거예요.

  • 결과 객체에는 장소 이름(place_name), 주소(address_name), 전화번호(phone), 위도(y), 경도(x) 등이 담겨 있어요
  • 검색 옵션으로 location(중심 좌표), radius(반경 미터), size(페이지당 결과 수, 최대 15) 등을 설정할 수 있어요
  • 페이지네이션 객체의 hasNextPage로 다음 페이지 존재 여부를 확인하고 nextPage()로 추가 결과를 가져올 수 있어요

검색 결과 지도에 표시하기

검색 결과를 마커로 지도에 찍으려면 각 결과의 좌표로 kakao.maps.Marker를 생성하고 지도에 추가하면 돼요. 이전 검색 결과 마커를 지우고 새 마커를 표시하려면 마커 배열을 유지하면서 setMap(null)을 호출해서 제거하는 패턴을 써요.

카테고리 검색으로 주변 장소 찾기

카테고리 코드 이해하기

카카오맵 API는 카테고리 코드를 통해 특정 종류의 장소만 검색할 수 있어요. 주요 카테고리 코드를 알아두면 편리해요.

  • MT1: 대형마트 / CS2: 편의점 / PS3: 어린이집·유치원
  • SC4: 학교 / AC5: 학원 / PK6: 주차장
  • OL7: 주유소·충전소 / SW8: 지하철역 / BK9: 은행
  • CT1: 문화시설 / AG2: 중개업소 / PO3: 공공기관
  • AT4: 관광명소 / AD5: 숙박 / FD6: 음식점 / CE7: 카페

categorySearch 메서드 활용

ps.categorySearch('FD6', callback, options)처럼 카테고리 코드를 첫 번째 인자로 넘기면 돼요. 반드시 location과 radius를 옵션으로 지정해야 해요. 반경은 최대 20,000미터(20km)까지 설정할 수 있어요.

현재 위치 기반 주변 검색

브라우저의 Geolocation API와 조합하면 현재 위치 주변 장소를 검색할 수 있어요. navigator.geolocation.getCurrentPosition()으로 위치를 얻고, 해당 좌표를 카카오맵 검색의 location 옵션에 넣어주면 돼요. HTTPS 환경에서만 Geolocation이 동작하는 점에 유의하세요.

주소와 좌표 변환하기

주소로 좌표 찾기 (geocoding)

주소 문자열을 위도·경도 좌표로 변환하는 것을 geocoding이라고 해요. 카카오맵 API에서는 kakao.maps.services.Geocoder 클래스가 이 역할을 해요. geocoder.addressSearch('서울 강남구 테헤란로', callback)처럼 사용하면 해당 주소의 좌표를 얻을 수 있어요. 도로명 주소와 지번 주소 모두 지원해요.

좌표로 주소 찾기 (reverse geocoding)

반대로 좌표를 주소로 변환하는 것은 reverse geocoding이에요. 지도를 클릭했을 때 그 위치의 주소를 보여주는 기능을 구현할 때 유용해요. geocoder.coord2Address(경도, 위도, callback)을 사용하면 되고, 결과에 도로명 주소와 지번 주소가 모두 포함돼요.

자동완성 검색창 구현하기

사용자가 검색어를 입력할 때마다 실시간으로 결과를 보여주는 자동완성 기능은 UX를 크게 향상시켜요. 하지만 입력할 때마다 API를 호출하면 요청 수가 너무 많아지니 debounce 처리(300ms 딜레이)를 적용하는 게 좋아요. 무료 쿼터는 하루 30만 건이지만 자동완성 미적용 시 금방 초과될 수 있어요.

마커 커스터마이징과 인포윈도우

커스텀 마커 이미지 적용

기본 빨간 마커 대신 원하는 이미지를 마커로 사용할 수 있어요. kakao.maps.MarkerImage로 이미지 객체를 만들고, 마커 생성 시 image 옵션에 넣어주면 돼요. 이미지 크기와 앵커 포인트(이미지에서 좌표에 해당하는 위치)도 지정할 수 있어서 핀 모양 이미지라면 아래쪽 끝을 앵커로 설정하면 정확하게 위치가 맞아요.

인포윈도우로 장소 정보 표시

마커를 클릭했을 때 팝업처럼 장소 정보를 보여주는 인포윈도우도 쉽게 만들 수 있어요. kakao.maps.InfoWindow로 HTML 내용을 담은 창을 생성하고, 마커 클릭 이벤트에서 infowindow.open(map, marker)를 호출하면 돼요. 인포윈도우 내부에 HTML을 자유롭게 넣을 수 있어서 이미지, 버튼, 링크 등 다양한 요소를 담을 수 있어요.

클러스터링으로 마커 정리하기

검색 결과가 많을 때 마커가 겹쳐서 보기 불편해지는 문제는 클러스터링으로 해결해요. libraries=clusterer를 SDK에 추가하고 kakao.maps.MarkerClusterer를 사용하면 근접한 마커들을 숫자가 표시된 하나의 클러스터 마커로 합쳐서 보여줘요. 지도를 확대하면 다시 개별 마커로 분리되는 인터랙티브한 경험을 제공해요.

API 사용량 관리와 주의사항

무료 쿼터와 유료 전환

카카오맵 API는 기본적으로 하루 30만 건까지 무료로 사용할 수 있어요. 그 이상은 유료 전환이 필요한데, Kakao Developers에서 비즈 앱으로 전환하면 돼요. 개인 프로젝트나 소규모 서비스라면 무료 쿼터로 충분한 경우가 대부분이에요. API 호출 횟수는 개발자 콘솔에서 실시간으로 모니터링할 수 있어요.

앱 키 보안 처리

JavaScript 키는 클라이언트 코드에 노출되는 특성상 완전한 보안은 어렵지만, 허용 도메인 설정으로 다른 사이트에서의 무단 사용은 막을 수 있어요. REST API 키는 서버 측에서만 사용해야 하고, 절대 클라이언트 코드에 넣으면 안 돼요.

모바일 환경 최적화

스마트폰에서도 지도가 잘 동작하려면 뷰포트 설정과 터치 이벤트 처리가 중요해요. 지도 영역의 CSS에 touch-action: none을 설정하면 스크롤과 지도 드래그가 충돌하는 문제를 방지할 수 있어요. 또한 모바일에서는 지도 레벨을 PC보다 한두 단계 높게 시작하면 더 넓은 영역을 한눈에 볼 수 있어서 UX가 좋아요.

마치며

카카오맵 API의 지도 검색 기능은 키 발급부터 키워드 검색, 카테고리 검색, 좌표 변환까지 다양한 기능을 제공해요. 처음에는 복잡해 보이지만 공식 문서와 예제 코드를 참고하면 금방 익힐 수 있어요. 특히 Kakao Developers 사이트의 샘플 코드는 바로 복사해서 테스트해볼 수 있게 잘 정리돼 있어요.

지도 서비스를 처음 개발한다면 키워드 검색부터 시작해서 마커 표시, 인포윈도우 순서로 차근차근 익혀나가는 것을 추천해요. 공식 가이드 외에도 GitHub에 다양한 실전 예제들이 공유돼 있으니 참고하면 훨씬 빠르게 원하는 기능을 구현할 수 있을 거예요.