카카오 MAP API 연동 가이드 — 근처 맛집 추천 앱 만든 실전 후기 (2026)
“오늘 뭐 먹지?” — 매일 점심마다 반복되는 이 질문을 해결하고 싶었습니다. 그래서 카카오 MAP API를 활용해서 내 위치 근처의 식당을 검색하고, 별점 4개 이상인 곳만 필터링해서 랜덤으로 추천해주는 앱을 만들었습니다. “결정장애 해결 앱”이라고 부르고 싶은 이 프로젝트를 만들면서 겪은 카카오 MAP API 연동의 전 과정을 공유합니다. API 키 발급부터 실전 코드까지, 이 글 하나로 카카오 MAP API 연동을 끝낼 수 있습니다.
카카오 MAP API란
카카오 MAP API는 카카오에서 제공하는 지도 및 위치 기반 서비스 API입니다. 지도를 웹페이지에 표시하는 것부터 키워드 검색, 카테고리 검색, 좌표 변환, 길찾기까지 다양한 기능을 무료로 사용할 수 있습니다.
카카오 MAP API가 사이드 프로젝트에 좋은 이유는 이렇습니다.
- 무료 사용량이 넉넉함: 일 300,000건까지 무료 (개인 프로젝트에는 충분)
- 한국 데이터가 가장 정확함: Google Maps보다 한국 내 상호명, 주소, 리뷰가 풍부함
- 문서가 한국어: 영어 문서와 씨름할 필요 없음
- JavaScript SDK 제공: 프론트엔드만으로 바로 구현 가능
카카오 MAP API 키 발급받기
카카오 MAP API를 사용하려면 먼저 API 키를 발급받아야 합니다. 5분이면 됩니다.
1단계: 카카오 개발자 등록
Kakao Developers에 접속해서 카카오 계정으로 로그인합니다. 처음이면 개발자 등록을 진행합니다.
2단계: 애플리케이션 생성
상단 메뉴 “내 애플리케이션” → “애플리케이션 추가하기” 클릭. 앱 이름(예: “오늘 뭐 먹지”)과 사업자명(개인이면 본인 이름)을 입력하고 저장합니다.
3단계: API 키 확인
생성된 앱을 클릭하면 “앱 키” 탭에서 4종류의 키를 확인할 수 있습니다.
| 키 종류 | 용도 |
|---|---|
| JavaScript 키 | 웹 브라우저에서 지도 SDK 사용 시 |
| REST API 키 | 서버에서 검색 API 호출 시 |
| Native 앱 키 | Android/iOS 앱 |
| Admin 키 | 관리용 (절대 노출 금지) |
웹에서 지도를 표시하려면 JavaScript 키, 키워드 검색 등 REST API를 호출하려면 REST API 키가 필요합니다. 제가 만든 앱에서는 둘 다 사용했습니다.
4단계: 플랫폼 등록
“앱 설정” → “플랫폼”에서 사용할 도메인을 등록합니다. 웹 플랫폼을 선택하고 사이트 도메인(예: https://pearsoninsight.com)을 추가합니다. 로컬 개발 시에는 http://localhost:3000도 등록해두면 편합니다. 도메인을 등록하지 않으면 API가 작동하지 않으니 꼭 설정하세요.
카카오 MAP API — 지도 띄우기 (기본)
가장 먼저 해야 할 건 웹페이지에 지도를 표시하는 것입니다. HTML에 카카오 지도 SDK를 로드하고 지도 객체를 생성합니다.
<!-- 1. 카카오 지도 SDK 로드 -->
<script src="https://dapi.kakao.com/v2/maps/sdk.js?appkey=YOUR_JAVASCRIPT_KEY&libraries=services"></script>
<!-- 2. 지도를 표시할 영역 -->
<div id="map" style="width:100%; height:400px;"></div>
<script>
// 3. 지도 생성
var mapContainer = document.getElementById('map');
var mapOption = {
center: new kakao.maps.LatLng(37.5665, 126.9780), // 서울 시청 좌표
level: 3 // 확대 레벨 (1~14, 숫자가 작을수록 확대)
};
var map = new kakao.maps.Map(mapContainer, mapOption);
</script>SDK URL 끝에 &libraries=services를 붙여야 키워드 검색 등 부가 기능을 사용할 수 있습니다. 이걸 빠뜨리면 지도는 뜨는데 검색이 안 됩니다.
카카오 MAP API — 내 위치 가져오기
“근처 맛집”을 찾으려면 먼저 사용자의 현재 위치를 알아야 합니다. 브라우저의 Geolocation API를 사용합니다.
// 현재 위치 가져오기
if (navigator.geolocation) {
navigator.geolocation.getCurrentPosition(function(position) {
var lat = position.coords.latitude; // 위도
var lng = position.coords.longitude; // 경도
// 지도 중심을 현재 위치로 이동
var currentPos = new kakao.maps.LatLng(lat, lng);
map.setCenter(currentPos);
// 현재 위치에 마커 표시
var marker = new kakao.maps.Marker({
position: currentPos,
map: map
});
}, function(error) {
alert('위치 정보를 가져올 수 없습니다.');
});
}주의할 점이 있습니다. HTTPS 환경에서만 Geolocation API가 작동합니다. HTTP에서는 브라우저가 위치 정보 요청을 차단합니다. SSL 설정이 안 되어 있다면 먼저 HTTPS를 적용하세요.
카카오 MAP API — 근처 식당 검색하기
이제 핵심입니다. 현재 위치 주변의 식당을 검색합니다. 카카오 MAP API의 키워드 장소 검색 기능을 사용합니다.
// 장소 검색 객체 생성
var ps = new kakao.maps.services.Places();
// 현재 위치 기준 근처 음식점 검색
function searchNearbyRestaurants(lat, lng) {
var options = {
location: new kakao.maps.LatLng(lat, lng),
radius: 1000, // 반경 1km
sort: kakao.maps.services.SortBy.DISTANCE // 거리순 정렬
};
ps.keywordSearch('음식점', function(data, status) {
if (status === kakao.maps.services.Status.OK) {
displayResults(data);
}
}, options);
}
// 검색 결과 처리
function displayResults(places) {
places.forEach(function(place) {
console.log(place.place_name); // 식당 이름
console.log(place.road_address_name); // 도로명 주소
console.log(place.phone); // 전화번호
console.log(place.place_url); // 카카오맵 상세 페이지
console.log(place.x, place.y); // 경도, 위도
});
}radius를 조절하면 검색 반경을 바꿀 수 있습니다. 500이면 500m, 2000이면 2km입니다. “음식점” 대신 “카페”, “한식”, “치킨” 등 구체적인 키워드를 넣으면 더 정확한 결과가 나옵니다.
카카오 MAP API — 별점 4점 이상 필터링
여기서 한 가지 중요한 사실을 알게 됐습니다. 카카오 MAP API 키워드 검색 응답에는 별점(rating) 데이터가 포함되지 않습니다. 검색 결과에 나오는 건 장소명, 주소, 전화번호, 카테고리, 좌표 정도입니다.
그래서 별점 필터링을 구현하기 위해 추가 작업이 필요했습니다.
방법 1: place_url을 활용한 크롤링
검색 결과에 place_url(카카오맵 상세 페이지 링크)이 포함되어 있습니다. 이 페이지에서 별점 정보를 가져오는 방식입니다. 다만 이 방법은 카카오 이용약관에 따라 제약이 있을 수 있으니 주의가 필요합니다.
방법 2: 카카오맵 카테고리 검색 + 자체 평점 시스템
카카오 MAP API의 카테고리 검색(categorySearch)으로 음식점 카테고리(FD6)를 조회하고, 자체적으로 사용자 평점 시스템을 구축하는 방법입니다.
// 카테고리로 음식점 검색 (FD6 = 음식점)
ps.categorySearch('FD6', function(data, status) {
if (status === kakao.maps.services.Status.OK) {
// 결과를 지도에 마커로 표시
data.forEach(function(place) {
var marker = new kakao.maps.Marker({
position: new kakao.maps.LatLng(place.y, place.x),
map: map
});
});
}
}, {
location: new kakao.maps.LatLng(lat, lng),
radius: 1000,
useMapBounds: true
});방법 3: 카카오 플레이스 API 조합 (제가 선택한 방법)
카카오 MAP API의 검색 결과에서 place_url의 ID를 추출한 뒤, 카카오 플레이스의 상세 정보에서 별점 데이터를 가져오는 방식입니다. 응답에서 별점이 4점 이상인 곳만 필터링하고, 그 중에서 랜덤으로 하나를 추천하도록 구현했습니다.
// 별점 필터링 + 랜덤 추천 (개념 코드)
function recommendRestaurant(places, minRating) {
// 별점 4점 이상만 필터
var filtered = places.filter(function(place) {
return place.rating >= minRating;
});
if (filtered.length === 0) {
alert('조건에 맞는 식당이 없습니다. 반경을 넓혀보세요.');
return;
}
// 랜덤 선택
var randomIndex = Math.floor(Math.random() * filtered.length);
var recommended = filtered[randomIndex];
alert('오늘의 추천: ' + recommended.place_name);
}카카오 MAP API — 지도에 마커와 인포윈도우 표시
추천된 식당을 지도 위에 마커로 표시하고, 클릭하면 상세 정보가 나오는 인포윈도우를 띄웁니다.
// 마커 생성
var marker = new kakao.maps.Marker({
position: new kakao.maps.LatLng(place.y, place.x),
map: map
});
// 인포윈도우 생성
var infoContent = '<div style="padding:8px;">' +
'<strong>' + place.place_name + '</strong><br>' +
place.road_address_name + '<br>' +
'⭐ ' + place.rating + '점<br>' +
'<a href="' + place.place_url + '" target="_blank">카카오맵에서 보기</a>' +
'</div>';
var infowindow = new kakao.maps.InfoWindow({
content: infoContent
});
// 마커 클릭 시 인포윈도우 표시
kakao.maps.event.addListener(marker, 'click', function() {
infowindow.open(map, marker);
});인포윈도우에 place_url 링크를 넣으면 사용자가 카카오맵에서 길찾기, 리뷰 확인 등을 바로 할 수 있어서 편리합니다.
카카오 MAP API 연동 시 주의할 점
직접 만들면서 삽질한 부분들을 정리합니다.
API 키 노출 주의
JavaScript 키는 브라우저 소스에 노출될 수밖에 없습니다. 그래서 플랫폼 도메인 제한을 반드시 설정해야 합니다. 카카오 개발자 콘솔에서 허용된 도메인에서만 API가 작동하도록 설정하면, 키가 노출되어도 다른 사이트에서는 사용할 수 없습니다.
REST API 키는 가능하면 서버 사이드에서만 사용하고, 프론트엔드 코드에 직접 넣지 마세요.
HTTPS 필수
Geolocation API가 HTTPS에서만 작동하므로, SSL 인증서가 없으면 위치 기반 기능 자체가 불가능합니다. Cloudflare 무료 SSL이나 Let’s Encrypt를 미리 적용하세요.
일일 사용량 제한
카카오 MAP API 무료 티어의 일일 한도는 300,000건입니다. 개인 프로젝트에서는 충분하지만, 검색 요청을 최적화하지 않으면 의외로 빨리 소진됩니다. 같은 위치에서 반복 검색하는 경우 결과를 캐싱해두는 게 좋습니다.
검색 결과 최대 45건
키워드 검색은 한 번에 최대 15건, 페이징을 포함하면 최대 45건(3페이지)까지 가져올 수 있습니다. 더 많은 결과가 필요하면 검색 반경을 나누거나 키워드를 세분화해야 합니다.
// 페이징으로 최대 45건 가져오기
ps.keywordSearch('음식점', function(data, status, pagination) {
if (status === kakao.maps.services.Status.OK) {
displayResults(data);
// 다음 페이지가 있으면 추가 로드
if (pagination.hasNextPage) {
pagination.nextPage();
}
}
}, options);카카오 MAP API — 앱 완성 후 느낀 점
완성된 “오늘 뭐 먹지” 앱의 동작 흐름은 이렇습니다.
- 앱 실행 → 현재 위치 자동 감지
- 반경 1km 내 음식점 검색
- 별점 4점 이상 필터링
- 필터링된 식당 중 랜덤 1곳 추천
- 지도에 마커 표시 + 상세 정보 인포윈도우
- “다시 추천” 버튼으로 다른 식당 추천
만들면서 느낀 건, 카카오 MAP API 자체는 쉬운데 별점 데이터 접근이 까다롭다는 점이었습니다. 기본 검색 API 응답에 별점이 없어서 추가 작업이 필요했던 부분이 가장 시간이 많이 들었습니다. 이 부분을 미리 알고 시작했으면 설계를 다르게 했을 겁니다.
그래도 카카오 MAP API는 한국에서 위치 기반 서비스를 만들 때 가장 현실적인 선택입니다. 한국 데이터의 정확도가 Google Maps보다 높고, 무료 사용량도 넉넉하고, 문서가 한국어라서 진입장벽이 낮습니다.
마무리 — 카카오 MAP API, 사이드 프로젝트의 좋은 시작점
카카오 MAP API는 진입장벽이 낮으면서도 실용적인 결과물을 만들 수 있는 API입니다. “오늘 뭐 먹지” 같은 간단한 아이디어도 위치 기반 검색 + 필터링 + 지도 표시를 조합하면 꽤 쓸 만한 앱이 됩니다. API 키 발급 5분, 지도 띄우기 10분이면 시작할 수 있으니 직접 만들어 보세요.
공식 문서는 카카오 지도 API 문서에서 확인할 수 있고, 더 다양한 예제는 카카오 지도 샘플에서 볼 수 있습니다.
다른 사이드 프로젝트가 궁금하면 월급 계산기 만들기 후기도 읽어보세요. 웹 개발 환경 구축이 필요하면 AWS EC2 워드프레스 설치 가이드를, API 키 보안이 걱정되면 Apache 디렉토리 리스팅 보안 가이드를 참고하세요.