카카오맵 API 사용법: 키 설정부터 지도·마커 표시까지

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

카카오맵 API는 웹사이트나 앱에 지도를 표시하고 위치 정보를 활용할 수 있는 기능을 제공합니다. 웹에서는 JavaScript SDK로 지도를 만들고 마커나 안내창을 표시할 수 있습니다. 지도 표시에는 키 종류, 도메인 등록, 사용 설정이 함께 적용됩니다.

카카오맵 API, 코드보다 콘솔에서 먼저 막힙니다

오시는 길 페이지에 지도가 안 뜨면 대개 키를 잘못 골랐거나 도메인을 빠뜨린 경우입니다. 사용 설정을 켜지 않았을 수도 있는데, 이 단계는 2024년 12월에 생겨서 그 전 사용법 글에는 없습니다.

카카오맵 API 키 발급과 사용 설정

메뉴명은 2025년 12월 콘솔 개편 이후 기준으로 적었습니다.

카카오맵 API 사용법, 지도를 띄우는 최소 코드

지도 영역의 크기 지정

<div id="map" style="width:500px;height:400px;"></div>처럼 지정합니다. 높이가 0이면 오류 없이 빈 화면만 뜹니다.

SDK를 불러온 뒤 Map 객체를 만듭니다.

appkey에는 JavaScript 키를 넣습니다.

<script src="//dapi.kakao.com/v2/maps/sdk.js?appkey=JavaScript키"></script>
<script>
  var map = new kakao.maps.Map(document.getElementById('map'),
    { center: new kakao.maps.LatLng(33.450701, 126.570667), level: 3 });
</script>

React처럼 스크립트를 늦게 불러오면 autoload=false를 붙이고 kakao.maps.load 콜백 안에서 지도를 만듭니다.

마커·인포윈도우와 주소 좌표 변환

주소 검색은 services 라이브러리가 맡습니다.

SDK 주소 뒤에 &libraries=services를 붙여야 Geocoder를 쓸 수 있고, 주소를 넘기면 위도·경도가 돌아옵니다.

받은 좌표에 마커와 인포윈도우를 올립니다.

var geocoder = new kakao.maps.services.Geocoder();
geocoder.addressSearch('제주특별자치도 제주시 첨단로 242', function(result, status) {
  if (status === kakao.maps.services.Status.OK) {
    var coords = new kakao.maps.LatLng(result[0].y, result[0].x);
    var marker = new kakao.maps.Marker({ map: map, position: coords });
    new kakao.maps.InfoWindow({ content: '<div>본점</div>' }).open(map, marker);
    map.setCenter(coords);
  }
});

반복 조회를 줄이기 위한 저장이나 캐시를 적용할 때는 제공자의 데이터 보관·이용 조건을 함께 확인합니다.

지도가 안 뜰 때 확인할 오류와 무료 쿼터

401 domain mismatched는 도메인 등록 문제입니다.

등록 도메인에 접속 주소가 빠져 있을 때 뜹니다. 포트와 서브도메인까지 맞춰 보세요.

403 disabled OPEN_MAP_AND_LOCAL service는 사용 설정 문제입니다.

사용 설정이 꺼져 있으면 뜹니다. 무료 쿼터가 없는 두 번째 앱에서 유료 설정 없이 호출해도 같은 오류가 납니다.

무료 쿼터와 유료 이용 조건은 API 종류와 앱 설정에 따라 확인합니다. 콘솔의 현재 이용량과 카카오의 최신 쿼터 안내를 기준으로 운영 범위를 정할 수 있습니다.

그래서 카카오맵 API 사용법에서는 어느 계정, 어느 앱에서 켤지부터 정해야 합니다. 이 지도는 누구의 카카오 계정, 어느 앱에서 운영하나요? 외주사 계정으로 켰다가 이관하며 키를 다시 맞추는 일이 잦습니다.

세부 설정과 지원 범위는 카카오맵 Web API 가이드를 참고해 보세요.

위치 정보를 서비스 경험으로 연결합니다

지도에 표시할 지점이 하나인지, 여러 매장을 검색해야 하는지에 따라 필요한 화면이 달라집니다. 이용자가 지도로 무엇을 하려는지부터 함께 살펴볼 수 있습니다.

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

지금 만들고 있는 서비스나 개선하고 싶은 부분이 있다면 아래 똑똑한개발자 링크로 편하게 이야기 남겨주세요. 함께 살펴보겠습니다. 감사합니다. :)