카카오맵 API 완벽 가이드 – 시작부터 활용까지 (2026)

작성자:

지도 기능이 필요한 웹사이트나 앱을 개발할 때, 카카오맵 API는 국내 개발자들이 가장 많이 사용하는 선택지 중 하나예요. 네이버 지도 API와 함께 한국 지역 데이터가 풍부하고, 한글 지명과 한국 도로명 주소 체계에 최적화되어 있어서 국내 서비스 개발에 매우 유용해요.

이 글에서는 카카오맵 API를 처음 시작하는 분들을 위해 카카오 개발자 계정 생성부터 API 키 발급, 기본 지도 표시, 마커 추가, 장소 검색 API까지 단계별로 자세하게 설명해 드릴게요. 2026년 현재 기준으로 최신 정보를 반영했어요.

카카오맵 API란?

카카오맵 API 개요

카카오맵 API는 카카오가 제공하는 지도 서비스를 개발자가 자신의 웹사이트나 앱에 삽입할 수 있게 해주는 인터페이스예요. 기본 지도 표시뿐 아니라 마커 추가, 정보창 표시, 장소 검색, 경로 탐색, 좌표 변환, 클러스터링 등 다양한 기능을 제공해요. JavaScript SDK와 REST API 방식을 모두 지원해요.

카카오맵 API의 특징

  • 한국 지역 최적화: 국내 도로명 주소, 지번 주소, 한글 검색에 최적화
  • 다양한 API 제공: 지도 표시, 장소 검색, 주소 검색, 좌표 변환, 로컬 검색, 키워드 검색 등
  • 모바일 지원: iOS/Android SDK도 함께 제공
  • 무료 제공: 일정 할당량 내에서 무료로 사용 가능
  • 상세한 공식 문서: developers.kakao.com에서 한글 문서 제공

카카오 개발자 계정 생성 및 앱 등록

카카오 개발자 계정 만들기

카카오맵 API를 사용하려면 먼저 카카오 개발자 계정이 필요해요. 설정 방법은 다음과 같아요.

  • 1단계: developers.kakao.com 접속
  • 2단계: 카카오 계정으로 로그인 (없으면 카카오 계정 생성 필요)
  • 3단계: 개발자 약관 동의 후 개발자 등록 완료
  • 4단계: 내 애플리케이션 → 애플리케이션 추가하기
  • 5단계: 앱 이름과 사업자 명 입력 후 저장

API 키 발급

앱 등록이 완료되면 다음과 같은 API 키들이 발급돼요.

  • 네이티브 앱 키: iOS/Android 앱 개발 시 사용
  • REST API 키: 서버 사이드 요청 시 사용
  • JavaScript 키: 웹 브라우저에서 SDK 사용 시 사용 (지도 API에서 주로 사용)
  • Admin 키: 서버 간 통신에 사용, 외부 노출 금지

웹에서 카카오맵을 표시할 때는 주로 JavaScript 키를 사용해요. 보안을 위해 ‘플랫폼’ 설정에서 허용된 도메인을 추가해야 해요.

카카오맵 JavaScript SDK 기본 사용법

SDK 로드 및 기본 지도 표시

HTML 파일에서 카카오맵을 표시하는 기본 코드 구조는 다음과 같아요. 먼저 head 태그에 SDK를 로드해요.

  • script 태그로 kakao maps SDK를 https://dapi.kakao.com/v2/maps/sdk.js?appkey=YOUR_APP_KEY 형태로 로드
  • 지도를 표시할 div 요소를 HTML에 준비 (예: id=”map”, 가로세로 크기 지정)
  • kakao.maps.Map 객체를 생성해 지도를 초기화
  • center 옵션에 kakao.maps.LatLng(위도, 경도)를 지정해 초기 중심 좌표 설정
  • level 옵션으로 초기 줌 레벨 설정 (1~14, 숫자 작을수록 확대)

마커 추가하기

지도에 마커를 추가하는 방법은 간단해요.

  • kakao.maps.Marker 객체를 생성하면서 position 옵션에 LatLng 좌표를 지정
  • setMap() 메서드로 마커를 지도에 표시
  • 커스텀 마커 이미지는 kakao.maps.MarkerImage 객체를 생성해 지정 가능
  • 마커 클릭 이벤트는 kakao.maps.event.addListener()로 추가

인포윈도우 (정보창) 추가

마커 클릭 시 정보를 표시하는 인포윈도우를 추가할 수 있어요.

  • kakao.maps.InfoWindow 객체를 생성하면서 content 옵션에 HTML 문자열을 지정
  • 마커 클릭 이벤트 핸들러에서 infowindow.open(map, marker) 호출
  • 다른 마커 클릭 시 이전 인포윈도우를 닫는 로직도 추가하면 좋아요

장소 검색 및 키워드 검색 API

장소 검색 API 개요

카카오맵의 장소 검색 API(Kakao Local API)는 키워드, 카테고리, 주소로 장소를 검색하는 기능을 제공해요. REST API 방식으로 호출하며, Authorization 헤더에 REST API 키를 포함해야 해요. 주요 엔드포인트는 다음과 같아요.

  • 키워드 검색: /v2/local/search/keyword.json
  • 카테고리 검색: /v2/local/search/category.json
  • 주소 검색: /v2/local/search/address.json
  • 좌표 → 주소 변환: /v2/local/geo/coord2address.json
  • 주소 → 좌표 변환: /v2/local/geo/address.json

키워드 검색 API 호출 예시

예를 들어 “서울 카페”를 검색하려면 다음과 같이 요청해요.

  • GET https://dapi.kakao.com/v2/local/search/keyword.json?query=서울+카페&page=1&size=15
  • 헤더: Authorization: KakaoAK {REST_API_KEY}
  • 응답 형식: JSON, documents 배열에 검색 결과 포함
  • 각 결과에는 place_name, address_name, x(경도), y(위도), phone 등 포함

검색 결과 지도에 표시하기

장소 검색 결과를 받아 지도에 마커로 표시하는 전체 흐름은 다음과 같아요.

  • 사용자가 검색어를 입력하면 키워드 검색 API 호출
  • 응답의 documents 배열을 순회하며 각 장소 좌표(x, y)로 마커 생성
  • 마커 클릭 시 장소 이름, 주소, 전화번호를 담은 인포윈도우 표시
  • 지도 범위를 모든 마커가 보이도록 setBounds() 메서드로 자동 조정

카카오맵 API 사용 시 주의사항

도메인 허용 설정

카카오맵 JavaScript SDK는 등록된 도메인에서만 사용할 수 있어요. 카카오 개발자 콘솔의 내 애플리케이션 → 플랫폼 → Web 설정에서 사이트 도메인을 등록해야 해요. 로컬 개발 시에는 http://localhost 또는 http://127.0.0.1도 등록해야 해요. 도메인 미등록 시 지도가 표시되지 않거나 오류가 발생해요.

일일 할당량 관리

카카오맵 API는 무료로 제공되지만 일일 사용 할당량이 있어요. 장소 검색 API는 기본 일일 300,000건(일부 API는 더 적을 수 있음)이 할당되며, 이를 초과하면 API 호출이 차단돼요. 상업적 서비스로 대량의 API 호출이 필요한 경우 카카오 개발자 채널을 통해 할당량 증가를 신청할 수 있어요.

API 키 보안

JavaScript 키는 웹 소스코드에 노출되는 것이 불가피하지만, 허용 도메인 설정을 통해 무단 사용을 방지할 수 있어요. 서버에서 사용하는 REST API 키나 Admin 키는 절대 클라이언트 코드에 노출하면 안 돼요. GitHub 등 공개 저장소에 API 키를 커밋하지 않도록 환경 변수로 관리하는 것이 중요해요.

카카오맵 API 활용 사례

매장 위치 안내

기업의 지점이나 매장 위치를 지도에 표시하는 가장 기본적인 활용 사례예요. 여러 매장 좌표를 마커로 표시하고, 클릭 시 매장 정보와 영업시간, 전화번호를 인포윈도우로 보여주는 방식이 널리 사용돼요.

부동산·숙박 서비스

부동산 매물이나 숙박 시설의 위치를 지도에 표시하고 클러스터링 기능으로 많은 마커를 효율적으로 표시하는 서비스에 많이 활용돼요. 지도 이동이나 줌 변경에 따라 해당 영역의 매물을 실시간으로 갱신하는 기능도 구현할 수 있어요.

배달·물류 추적

배달 경로나 물류 차량의 실시간 위치를 지도에 표시하는 서비스에도 활용돼요. WebSocket이나 주기적인 API 폴링을 통해 마커 위치를 실시간으로 업데이트하는 구조로 구현할 수 있어요.

정리

카카오맵 API는 한국 주소 데이터와 한글 검색에 최적화되어 있어 국내 서비스 개발에 매우 유용한 도구예요. 개발자 계정 생성, API 키 발급, 도메인 설정의 기본 준비 과정이 끝나면 JavaScript SDK로 지도를 표시하고 마커를 추가하는 것은 생각보다 간단해요.

장소 검색, 경로 탐색, 좌표 변환 등 다양한 REST API도 함께 활용하면 더 풍부한 위치 기반 서비스를 구현할 수 있어요. 공식 문서(developers.kakao.com)가 한글로 잘 정리되어 있으니 꼭 참고하면서 개발해 보세요.

댓글 남기기