카카오맵 API 연동 — 주소 검색, 마커, 반경 검색

카카오맵 API란? Google Maps 대비 장단점

카카오맵 API는 국내 서비스에서 가장 많이 사용되는 지도 API 중 하나입니다. Google Maps에 비해 한국 지역 데이터의 정확도가 높고, 국내 주소 체계(도로명/지번 주소)에 최적화되어 있어 국내 서비스 개발에 적합합니다. 특히 카카오 로컬 API와 연동하면 장소 검색, 반경 검색, 키워드 검색까지 강력한 기능을 무료로 사용할 수 있습니다.

이번 글에서는 SvelteKit 프로젝트에 카카오맵 API를 연동하는 방법을 단계별로 살펴봅니다. 주소 검색, 마커 표시, 반경 내 장소 검색을 실전 코드와 함께 구현해 보겠습니다.

카카오 Developers 앱 등록 및 API 키 발급

카카오맵 API를 사용하려면 카카오 Developers(developers.kakao.com)에서 앱을 생성하고 JavaScript API 키를 발급받아야 합니다. 앱 생성 후 “플랫폼” 설정에서 사이트 도메인을 반드시 등록해야 합니다. 로컬 개발 시에는 http://localhost:5173도 추가해두세요.

SvelteKit에 카카오맵 SDK 로드하기

SvelteKit에서 카카오맵 SDK를 사용하는 가장 안전한 방법은 onMount 내에서 동적으로 스크립트를 로드하는 것입니다. SSR 환경에서 window 객체가 존재하지 않기 때문에, 클라이언트 사이드에서만 초기화해야 합니다.

<!-- src/routes/map/+page.svelte -->
<script>
  import { onMount } from 'svelte';

  let mapContainer;
  let map;

  onMount(async () => {
    // 카카오맵 SDK 동적 로드
    await new Promise((resolve, reject) => {
      const script = document.createElement('script');
      script.src = `//dapi.kakao.com/v2/maps/sdk.js?appkey=${import.meta.env.VITE_KAKAO_MAP_KEY}&autoload=false&libraries=services,clusterer`;
      script.onload = resolve;
      script.onerror = reject;
      document.head.appendChild(script);
    });

    // SDK 초기화 후 지도 생성
    window.kakao.maps.load(() => {
      const options = {
        center: new window.kakao.maps.LatLng(37.5665, 126.9780), // 서울 시청
        level: 3
      };
      map = new window.kakao.maps.Map(mapContainer, options);
    });
  });
</script>

<div bind:this={mapContainer} style="width:100%; height:500px;"></div>

.env 파일에 VITE_KAKAO_MAP_KEY=your_javascript_key를 추가하고, libraries=services를 포함해야 장소 검색 기능을 사용할 수 있습니다. clusterer는 마커 클러스터링이 필요할 때 추가합니다.

주소 검색 기능 구현

카카오 우편번호 서비스(daum.postcode)를 활용하면 팝업 형태의 주소 검색 UI를 쉽게 추가할 수 있습니다. 사용자가 주소를 선택하면 해당 위치로 지도가 이동하고 마커가 생성됩니다.

// 주소 검색 및 지도 이동 함수
function searchAddress() {
  new window.daum.Postcode({
    oncomplete: function(data) {
      // 도로명 주소 우선, 없으면 지번 주소
      const addr = data.roadAddress || data.jibunAddress;
      
      // 주소로 좌표 변환
      const geocoder = new window.kakao.maps.services.Geocoder();
      geocoder.addressSearch(addr, function(result, status) {
        if (status === window.kakao.maps.services.Status.OK) {
          const coords = new window.kakao.maps.LatLng(result[0].y, result[0].x);
          
          // 기존 마커 제거 후 새 마커 생성
          if (marker) marker.setMap(null);
          marker = new window.kakao.maps.Marker({
            map: map,
            position: coords
          });
          
          // 지도 중심 이동 및 줌 레벨 조정
          map.setCenter(coords);
          map.setLevel(3);
          
          // 인포윈도우 표시
          const infowindow = new window.kakao.maps.InfoWindow({
            content: `<div style="padding:5px;font-size:12px;">${addr}</div>`
          });
          infowindow.open(map, marker);
        }
      });
    }
  }).open();
}

반경 내 장소 검색 구현

카카오 로컬 API의 keywordSearch 또는 categorySearch를 사용하면 특정 좌표를 기준으로 반경 내 장소를 검색할 수 있습니다. 예를 들어 현재 위치에서 반경 1km 내 카페나 음식점을 찾는 기능을 구현할 수 있습니다.

// 반경 내 키워드 검색 함수
function searchNearby(keyword, lat, lng, radius = 1000) {
  const places = new window.kakao.maps.services.Places();
  
  places.keywordSearch(keyword, function(data, status, pagination) {
    if (status === window.kakao.maps.services.Status.OK) {
      // 기존 마커 전체 제거
      markers.forEach(m => m.setMap(null));
      markers = [];
      
      data.forEach((place, index) => {
        const position = new window.kakao.maps.LatLng(place.y, place.x);
        const marker = new window.kakao.maps.Marker({
          map: map,
          position: position
        });
        
        // 마커 클릭 시 인포윈도우 표시
        window.kakao.maps.event.addListener(marker, 'click', function() {
          const infoContent = `
            <div style="padding:10px;min-width:200px;">
              <strong>${place.place_name}</strong><br>
              <span style="color:#666;">${place.road_address_name}</span><br>
              <span>거리: ${place.distance}m</span>
            </div>
          `;
          const infowindow = new window.kakao.maps.InfoWindow({ content: infoContent });
          infowindow.open(map, marker);
        });
        
        markers.push(marker);
      });
      
      // 검색 결과가 여러 페이지인 경우 처리
      if (pagination.hasNextPage) {
        console.log(`총 ${pagination.totalCount}개 결과 중 ${data.length}개 표시`);
      }
    }
  }, {
    location: new window.kakao.maps.LatLng(lat, lng),
    radius: radius,
    sort: window.kakao.maps.services.SortBy.DISTANCE  // 거리순 정렬
  });
}

현재 위치 기반 지도 초기화

브라우저의 Geolocation API와 카카오맵을 결합하면 사용자의 현재 위치를 기반으로 지도를 초기화할 수 있습니다. navigator.geolocation.getCurrentPosition으로 위경도를 받아 카카오맵의 중심 좌표로 설정하면 됩니다. 단, HTTPS 환경에서만 Geolocation이 동작하므로 배포 시 SSL 설정을 반드시 확인하세요.

Google Maps 대비 카카오맵의 장단점

카카오맵의 장점: 국내 주소 데이터 정확도가 높고, 한국어 장소명 검색이 우수합니다. 월 300,000건까지 무료이며, 카카오 로컬 API와 통합이 용이합니다. 도로명/지번 주소 변환이 간단하고, 국내 POI(관심지점) 데이터가 풍부합니다.

카카오맵의 단점: 해외 서비스에는 적합하지 않고, TypeScript 타입 정의가 공식으로 제공되지 않아 커뮤니티 패키지를 별도로 설치해야 합니다. Google Maps에 비해 글로벌 문서와 커뮤니티가 적습니다. 복잡한 커스텀 스타일링은 Google Maps보다 제한적입니다.

코드벤터는 국내외 다양한 플랫폼 개발 경험을 바탕으로, 서비스 특성에 맞는 지도 API 선택부터 카카오맵·Google Maps·Naver Maps 연동까지 최적의 솔루션을 제공합니다. 지도 기반 서비스 개발이나 위치 기반 기능 구현이 필요하다면 코드벤터와 함께 빠르고 안정적으로 구축해보세요.