웹사이트나 앱에 지도 기능을 추가하고 싶다면 카카오맵 API가 좋은 선택이에요. 카카오맵 API는 국내 지도 데이터를 바탕으로 다양한 지도 서비스를 구현할 수 있게 해줘요. 마커 표시, 경로 탐색, 장소 검색 등 다양한 기능을 제공하며, 무료로 사용할 수 있는 범위도 넉넉해서 개인 개발자나 스타트업에서도 많이 활용해요.
이 글에서는 카카오맵 지도 API를 처음 사용하는 분들을 위해 API 키 발급부터 기본 지도 표시, 마커 추가, 자주 쓰는 기능 구현 방법까지 단계별로 안내해 드릴게요.
카카오맵 API 개요
카카오맵 API 종류
카카오맵에서 제공하는 API는 크게 세 가지 종류로 나뉘어요.
- JavaScript API: 웹 브라우저에서 지도를 표시하고 조작하는 API. 가장 많이 사용돼요.
- REST API: 서버 사이드에서 주소 검색, 좌표 변환, 로컬 검색 등을 처리하는 API.
- Android/iOS SDK: 모바일 앱 개발을 위한 네이티브 SDK.
무료 사용 한도
카카오맵 API는 일정 한도까지 무료로 사용할 수 있어요. 무료 한도를 초과하면 추가 비용이 발생하거나 서비스가 제한될 수 있어요.
- JavaScript API: 일일 30만 건 무료
- REST API (주소 검색): 일일 30만 건 무료
- REST API (로컬 검색): 일일 30만 건 무료
- 초과 시 카카오 고객 센터를 통해 사용 확대 가능
API 키 발급 방법
1단계: 카카오 개발자 센터 가입
카카오맵 API를 사용하려면 카카오 개발자 센터에 가입하고 앱을 등록해야 해요. 카카오 계정이 있으면 별도 회원가입 없이 개발자 센터에 로그인할 수 있어요.
- 접속 주소: developers.kakao.com
- 카카오 계정으로 로그인
- 개발자 등록 (최초 1회)
2단계: 애플리케이션 등록
로그인 후 “내 애플리케이션” 메뉴에서 새 애플리케이션을 등록해요. 앱 이름과 사업자 이름을 입력하면 앱이 생성돼요.
- 내 애플리케이션 → 애플리케이션 추가하기
- 앱 이름, 사업자 이름 입력
- 앱 생성 완료
3단계: API 키 확인 및 도메인 등록
앱이 생성되면 앱 키 목록에서 JavaScript API에 사용할 키를 확인할 수 있어요. 웹사이트에서 사용할 경우 “Web” 플랫폼에 사이트 도메인을 등록해야 해요. 미등록 도메인에서 사용하면 API 호출이 차단돼요.
- 앱 설정 → 앱 키 → JavaScript 키 확인
- 플랫폼 → Web → 사이트 도메인 등록
- 개발 중이라면 “http://localhost:포트번호” 등록
- 운영 중이라면 실제 도메인 등록
기본 지도 표시하기
HTML 기본 코드 구조
카카오맵 JavaScript API를 이용해 웹페이지에 지도를 표시하는 기본 코드 구조는 다음과 같아요.
- HTML head 태그 안에 API 스크립트 로드
- 지도가 표시될 div 태그 추가
- JavaScript로 지도 초기화 코드 작성
- appkey 파라미터에 발급받은 API 키 입력
지도 초기화 코드 예시
스크립트 src에 API 키를 포함해 로드한 후, kakao.maps.Map 객체를 생성해 지도를 초기화해요. center에 위도·경도 좌표를 지정하고 level로 확대 수준을 설정해요.
- kakao.maps.LatLng(위도, 경도)로 중심 좌표 설정
- level 값이 낮을수록 더 확대된 지도 표시
- level 1~14 사이 값 사용 (1이 가장 확대)
- mapTypeId로 일반, 스카이뷰, 하이브리드 지도 타입 설정
마커 추가하기
기본 마커 추가
지도에 마커(핀)를 표시하려면 kakao.maps.Marker 객체를 생성해요. position에 마커 위치, map에 표시할 지도를 지정하면 돼요.
- kakao.maps.Marker 객체 생성
- position: new kakao.maps.LatLng(위도, 경도)
- map 속성에 생성한 map 객체 전달
- 여러 마커를 배열로 관리 가능
커스텀 마커 이미지 사용
기본 마커 대신 원하는 이미지로 마커를 꾸밀 수 있어요. kakao.maps.MarkerImage 객체를 생성해 이미지 URL, 크기, 기준점을 설정하면 돼요.
- kakao.maps.MarkerImage(이미지URL, 크기, 옵션)
- 크기: new kakao.maps.Size(가로, 세로)
- 기준점(offset): 이미지에서 좌표가 가리킬 지점
- SVG, PNG 등 다양한 이미지 형식 지원
인포윈도우 (말풍선) 표시하기
기본 인포윈도우 추가
마커 클릭 시 정보를 표시하는 말풍선(인포윈도우)을 추가할 수 있어요. kakao.maps.InfoWindow 객체를 생성하고 마커 클릭 이벤트와 연결하면 돼요.
- kakao.maps.InfoWindow 객체 생성
- content 속성에 표시할 HTML 내용 작성
- kakao.maps.event.addListener로 클릭 이벤트 연결
- infowindow.open(map, marker)로 열기
여러 마커와 인포윈도우 관리
여러 마커가 있을 때 한 번에 하나의 인포윈도우만 열리도록 관리하는 방법이 중요해요. 마커 클릭 시 이전 인포윈도우를 닫고 새 인포윈도우를 여는 방식으로 구현하면 깔끔해요.
주소 검색 및 좌표 변환
주소로 좌표 얻기
REST API 또는 JavaScript API를 이용해 주소를 좌표로 변환할 수 있어요. 사용자가 입력한 주소를 지도 위의 좌표로 변환해 마커를 표시하는 기능에 자주 활용돼요.
- kakao.maps.services.Geocoder 사용
- addressSearch(주소, 콜백함수) 호출
- 결과에서 x(경도), y(위도) 값 추출
- REST API 사용 시 주소 검색 엔드포인트: https://dapi.kakao.com/v2/local/search/address.json
좌표로 주소 얻기 (역지오코딩)
반대로 좌표(위도·경도)에서 주소를 가져올 수도 있어요. 지도 클릭 시 해당 위치의 주소를 표시하는 기능에 활용돼요.
- coord2Address(경도, 위도, 콜백함수) 호출
- 결과에서 address 또는 road_address 확인
카카오맵 API 사용 시 유의사항
API 키 보안
JavaScript API 키는 클라이언트 코드에 노출되므로 도메인 등록으로 무단 사용을 제한하는 것이 중요해요. REST API 키는 절대 클라이언트 코드에 노출하지 말고 서버에서만 사용해야 해요.
- JavaScript 키: 도메인 등록으로 보안 설정
- REST API 키: 서버 사이드에서만 사용
- API 키 유출 시 즉시 재발급
HTTPS 환경 권장
일부 카카오맵 API 기능은 HTTPS 환경에서만 정상 동작해요. 현재 위치 가져오기 등 브라우저 보안 API와 연동되는 기능은 HTTP에서 작동하지 않으므로 운영 서버에는 반드시 HTTPS를 적용해야 해요.
마무리
카카오맵 지도 API는 카카오 개발자 센터에서 API 키를 발급받아 도메인을 등록한 후, JavaScript API 코드를 웹페이지에 삽입하면 바로 사용할 수 있어요. 기본 지도 표시부터 마커, 인포윈도우, 주소 검색까지 다양한 기능을 제공해요.
처음 사용한다면 카카오 개발자 사이트의 공식 가이드와 샘플 코드를 참고하면 훨씬 빠르게 시작할 수 있어요. 일일 30만 건까지 무료로 사용할 수 있으니 개인 프로젝트나 소규모 서비스에도 부담 없이 활용해 보세요.