카카오 지도·로컬 API 활용하기

developers.kakao.com에서 5분이면 끝납니다. 1) 카카오 계정으로 로그인 → [내 애플리케이션] → 앱 추가 2) [앱 키]에서 키 4개 확인 — 이 중 2개만 기억하세요 · JavaScript 키: 지도를 '화면에 띄울' 때 (지도 JavaScript API) · REST API 키: 주소 변환·장소검색·길찾기 등 '데이터를 받아올' 때 (네이티브 앱 키·Admin 키는 지금 필요 없습니다) 3) 지도를 띄울 거면 [플랫폼] → Web 플랫폼 등록 후, 앱 키의 JavaScript SDK 도메인에 내 주소 등록 · 개발 중: http://localhost:3000 (포트까지 정확히) · 배포 후: https://내서비스.com ※ 등록된 도메인에서만 지도가 뜹니다. '지도가 하얗게만 나오면' 90%는 이것입니다.

HTML 세 조각이면 끝입니다. 지도를 담을 div, SDK 스크립트, 생성 코드. <div id="map" style="width:100%;height:400px;"></div> <script src="//dapi.kakao.com/v2/maps/sdk.js?appkey=JavaScript키"></script> <script> var container = document.getElementById('map'); var options = { center: new kakao.maps.LatLng(33.450701, 126.570667), // (위도, 경도) 순서 주의! level: 3 // 작을수록 확대 }; var map = new kakao.maps.Map(container, options); </script> 함정 하나: LatLng(위도, 경도)인데, REST API의 x,y는 x=경도, y=위도입니다. 순서가 반대라 헷갈리기 쉬우니 주석으로 표시해 두세요.

스크립트 주소 뒤에 libraries=services를 붙이면 장소 검색과 주소-좌표 변환이 됩니다. <script src="//dapi.kakao.com/v2/maps/sdk.js?appkey=키&libraries=services"></script> // 마커 하나 찍기 var marker = new kakao.maps.Marker({ position: new kakao.maps.LatLng(33.450701, 126.570667) }); marker.setMap(map); // 주소 → 좌표 변환 후 지도 중심 이동 var geocoder = new kakao.maps.services.Geocoder(); geocoder.addressSearch('경남 창원시 의창구 중앙대로 151', function(result, status) { if (status === kakao.maps.services.Status.OK) { var coord = new kakao.maps.LatLng(result[0].y, result[0].x); map.setCenter(coord); new kakao.maps.Marker({ map: map, position: coord }); } }); // 키워드로 장소 검색 (예: 주변 약국) var ps = new kakao.maps.services.Places(); ps.keywordSearch('약국', function(data, status) { if (status === kakao.maps.services.Status.OK) { // data[i].place_name, .address_name, .x, .y, .phone ... } }); 그 외 라이브러리: clusterer(마커 수백 개를 묶어 표시), drawing(지도 위에 직접 그리기). 여러 개는 libraries=services,clusterer,drawing 처럼 쉼표로.

지도 없이 데이터만 필요할 때 씁니다. 전부 같은 패턴: GET + 헤더에 키. 공통 헤더: Authorization: KakaoAK REST_API_키 · 주소 → 좌표 (지오코딩) GET https://dapi.kakao.com/v2/local/search/address.json?query=전북 삼성동 100 → documents[0].x(경도), .y(위도), .address(지번 상세), .road_address(도로명 상세) · 좌표 → 주소 (역지오코딩) GET https://dapi.kakao.com/v2/local/geo/coord2address.json?x=127.4230849&y=37.0789562 → 지번 주소와 도로명 주소 (도로명은 없을 수도 있음) · 좌표 → 행정구역(법정동/행정동 코드) GET https://dapi.kakao.com/v2/local/geo/coord2regioncode.json?x=127.1086228&y=37.4012191 → region_type 'B'(법정동), 'H'(행정동) + code · 좌표계 변환 (WGS84 ↔ WTM 등) GET https://dapi.kakao.com/v2/local/geo/transcoord.json?x=...&y=...&input_coord=WTM&output_coord=WGS84 실무 팁: 주소 목록 CSV를 지도에 찍고 싶으면 '주소→좌표'를 행마다 돌려 x,y를 채운 뒤, 그 결과로 지도에 마커를 찍으면 됩니다. 에이전트에게 그대로 시키면 됩니다.

· 키워드로 장소 검색 GET https://dapi.kakao.com/v2/local/search/keyword.json?query=카카오프렌즈&x=127.0628310&y=37.5143226&radius=20000 → 장소명·주소·전화번호·좌표·카카오맵 상세 URL(place_url) x,y,radius: 이 좌표 중심 반경(미터, 최대 20000) / sort=distance: 가까운 순 page(최대 45)·size(최대 15)로 페이징, meta.is_end로 마지막 페이지 판단 · 카테고리로 장소 검색 (키워드 없이 '주변 OOO 전부') GET https://dapi.kakao.com/v2/local/search/category.json?category_group_code=PM9&x=경도&y=위도&radius=2000 → x,y,radius 또는 rect(사각 범위) 중 하나는 필수 자주 쓰는 카테고리 코드: FD6 음식점 · CE7 카페 · MT1 대형마트 · CS2 편의점 · PK6 주차장 · OL7 주유소/충전소 SW8 지하철역 · BK9 은행 · HP8 병원 · PM9 약국 · PS3 어린이집/유치원 · SC4 학교 CT1 문화시설 · AT4 관광명소 · AD5 숙박 · PO3 공공기관 · AG2 중개업소 · AC5 학원 활용 예: '우리 시군 음식점 목록 뽑기' → 시청 좌표 + FD6 + radius 20000 + page 돌리기.

자동차 경로의 거리·예상 소요시간·통행료·택시요금을 숫자로 받습니다. 운영 주체가 카카오모빌리티라 문서는 developers.kakaomobility.com에 있지만, 키는 같은 REST API 키입니다. GET https://apis-navi.kakaomobility.com/v1/directions?origin=127.1101531,37.3947271&destination=127.1082437,37.4019371 Authorization: KakaoAK REST_API_키 주요 파라미터 (좌표는 '경도,위도' 문자열): · origin, destination (필수) · waypoints: 경유지, 'x,y|x,y' 형태 (최대 5개) · priority: RECOMMEND(추천, 기본) / TIME(최단시간) / DISTANCE(최단거리) · avoid: ferries|toll|motorway|schoolzone|uturn (|로 여러 개) · alternatives: true면 대안경로도 함께 응답에서 꺼낼 것: · routes[0].result_code (0이면 성공) · routes[0].summary.distance (미터), .duration (초) · routes[0].summary.fare.taxi (예상 택시요금, 원), .fare.toll (통행료) · routes[0].sections[].roads → 실제 도로 좌표열 (지도 위에 경로를 '그릴' 때 사용) 활용 예: '출발지 목록 × 목적지 목록' 소요시간 표 만들기, 출장 시간표, 배송 경로 비교. 대중교통·도보 경로는 이 API가 아니라 지도 URL(다음 섹션)로 연결합니다.

API 키 없이 링크만으로 카카오맵을 열 수 있습니다. PC/모바일을 자동으로 맞춰 줍니다. · 장소 보기: https://map.kakao.com/link/map/카카오판교아지트,37.3952969,127.1104493 · 길찾기(도착): https://map.kakao.com/link/to/카카오판교아지트,37.3952969,127.1104493 · 길찾기(수단): https://map.kakao.com/link/by/car/출발지,위도,경도/도착지,위도,경도 (car 자동차 · traffic 대중교통 · walk 도보 · bicycle 자전거) · 로드뷰: https://map.kakao.com/link/roadview/37.3952969,127.1104493 · 검색결과: https://map.kakao.com/link/search/경남 창원 카페 회의록·안내문에 '오시는 길' 버튼을 달거나, 명단 옆에 길찾기 링크를 붙일 때 이것으로 충분합니다. 장소 ID(link/map/18577297)는 키워드 검색 API 응답의 id 값입니다.

① REST API 키는 서버에서만 쓰세요. 브라우저 JS에 넣으면 소스 보기로 훔쳐갑니다. Next.js라면 Route Handler(/app/api/...)에서 호출하고 결과만 화면으로. 브라우저에서 dapi.kakao.com을 직접 부르면 CORS 에러도 납니다. 반대로 JavaScript 키는 화면에 노출돼도 도메인 등록으로 보호됩니다. ② 좌표 순서 함정: REST API의 x=경도, y=위도 / JavaScript API의 LatLng(위도, 경도). 반대입니다. directions의 origin도 '경도,위도'. ③ 쿼터: 로컬 API는 일 10만 호출, 지도 API는 일 30만 호출 수준의 무료 쿼터가 있습니다(정확한 수치·변동은 [쿼터] 문서에서 확인). 개인·교육 용도는 충분하고, 초과가 필요하면 제휴 문의입니다. ④ 결과가 없을 때: 주소 검색은 지번·도로명 둘 다 되지만, 결과 0건이면 analyze_type=similar(기본)인지, 오타는 없는지부터. 장소 검색은 x,y,radius 없이 전국 검색하면 엉뚱한 지역이 먼저 나올 수 있으니 중심 좌표를 주세요. ⑤ 키가 새면 즉시 재발급하세요. GitHub에 올라간 키는 몇 분 안에 수집됩니다.

바이브코딩으로 붙일 때는 '키는 .env에, REST는 서버에서'만 못 박으면 됩니다. [지도 페이지 만들기] 카카오 지도 JavaScript API로 주소 목록을 지도에 표시하는 페이지를 만들어 주세요. - JavaScript 키는 NEXT_PUBLIC_KAKAO_MAP_KEY 환경변수로 읽고, 키 값을 코드에 직접 쓰지 마세요 - 주소 목록은 addresses.ts에 상수로 두고, 페이지 로드 시 Geocoder.addressSearch로 좌표 변환 후 마커를 찍으세요 - 마커 클릭 시 장소명과 '길찾기' 링크(map.kakao.com/link/to/이름,위도,경도)가 있는 인포윈도우를 띄우세요 - 완료 조건: npm run dev에서 지도가 보이고 마커 3개 클릭 동작 [소요시간 표 만들기] 카카오모빌리티 길찾기 API로 출발지 3곳 × 목적지 5곳의 예상 소요시간 표를 만들어 주세요. - REST API 키는 KAKAO_REST_API_KEY 환경변수로, 반드시 Route Handler(/api/directions)에서만 호출하고 브라우저에는 결과만 내려주세요 - origin/destination은 '경도,위도' 형식, priority=RECOMMEND - routes[0].summary의 distance(미터→km)와 duration(초→분)만 표에 표시 - 호출 사이에 200ms 간격을 두고, result_code가 0이 아니면 '경로 없음'으로 표시 키 발급·도메인 등록은 사람이 합니다. '도메인 등록까지 제가 해야 하는 단계를 알려주세요'라고 덧붙이면 절차도 정리해 줍니다.