카카오맵 API는 카카오에서 제공하는 지도 서비스를 개발자가 자신의 웹사이트나 앱에 통합할 수 있도록 해주는 강력한 도구예요. 그 중에서도 길찾기 기능은 출발지와 목적지를 입력하면 최적 경로를 계산해주는 기능으로, 서비스에 내비게이션이나 위치 기반 경로 안내 기능을 넣고 싶은 개발자들이 많이 활용해요.
이 글에서는 카카오맵 길찾기 API를 활용하는 방법을 개발자 관점에서 단계별로 안내해 드릴게요. API 키 발급부터 REST API 호출, 응답 데이터 파싱, 그리고 실제 활용 예시까지 체계적으로 정리했어요.
카카오맵 API 개요
카카오맵 API 종류
카카오에서 제공하는 지도 관련 API는 크게 두 가지 계열로 나뉘어요. 첫 번째는 카카오맵 JavaScript API로, 웹 브라우저에서 지도를 시각적으로 표시하고 인터랙션을 구현할 때 사용해요. 두 번째는 카카오 로컬 REST API로, 서버 사이드에서 장소 검색, 주소 변환, 경로 탐색 등의 기능을 HTTP 요청으로 호출할 때 사용해요.
길찾기 관련 API 기능
카카오 API에서 길찾기와 관련된 주요 기능은 다음과 같아요.
- 카카오 내비 URL 스킴: 카카오맵 앱의 길찾기 화면을 직접 열어주는 URL 방식
- 카카오 모빌리티 API: 자동차 길찾기 REST API (출발지 → 목적지 경로 계산)
- 로컬 API 좌표계 변환: 주소를 좌표(위경도)로 변환하는 기능
- 거리·시간 계산: 두 지점 간 소요 시간 및 거리 계산
카카오 개발자 콘솔 가입
카카오맵 API를 사용하려면 먼저 카카오 개발자 사이트(developers.kakao.com)에 가입해야 해요. 카카오 계정으로 로그인한 후 애플리케이션을 등록하면 API 키를 발급받을 수 있어요. API 키에는 REST API 키, JavaScript 키, Native 앱 키 세 가지가 있으며, 사용 목적에 맞는 키를 사용해야 해요.
카카오 API 키 발급 방법
애플리케이션 등록
API 키 발급 절차는 다음과 같아요.
- developers.kakao.com 접속 및 카카오 계정으로 로그인
- ‘내 애플리케이션’ 메뉴 → ‘애플리케이션 추가하기’ 클릭
- 앱 이름, 회사명 입력 후 저장
- 생성된 앱에서 ‘앱 키’ 확인 (REST API 키 등)
- 플랫폼 설정: 사용할 플랫폼(Web, Android, iOS) 등록 및 도메인/패키지명 입력
카카오모빌리티 API 활성화
자동차 길찾기 기능을 위한 카카오 모빌리티 API는 별도로 활성화해야 해요. ‘카카오 개발자 콘솔 → 내 애플리케이션 → 카카오 로그인/권한 설정’에서 필요한 API를 활성화하거나, 유료 서비스의 경우 별도 신청이 필요해요. 무료 할당량과 유료 전환 조건을 미리 확인하는 게 좋아요.
카카오맵 길찾기 URL 방식
카카오맵 앱 길찾기 URL 스킴
앱이나 웹에서 카카오맵 길찾기를 여는 가장 간단한 방법은 URL 스킴을 활용하는 거예요. 아래와 같은 형식의 URL을 호출하면 카카오맵 앱이 열리면서 길찾기 화면으로 이동해요.
- 카카오맵 앱 직접 열기: kakaomap://route?sp=위도,경도&ep=위도,경도&by=CAR
- 웹에서 열기: https://map.kakao.com/link/to/목적지명,위도,경도
by 파라미터는 이동 수단을 지정하며, CAR(자동차), PUBLICTRANSIT(대중교통), WALK(도보) 등을 사용할 수 있어요.
좌표 기반 길찾기 URL
목적지의 위경도 좌표를 알고 있다면 다음과 같이 URL을 구성할 수 있어요. 출발지를 지정하지 않으면 현재 위치에서 출발하는 방식으로 카카오맵이 처리해요. 웹 페이지에서 버튼 클릭 시 카카오맵을 열어 길찾기를 안내하는 기능을 구현할 때 많이 활용돼요.
카카오 REST API를 이용한 경로 탐색
카카오 로컬 API – 좌표 변환
길찾기를 위해서는 먼저 주소를 위경도 좌표로 변환해야 해요. 카카오 로컬 API의 주소 검색 기능을 사용하면 돼요.
- 엔드포인트: GET https://dapi.kakao.com/v2/local/search/address.json
- 헤더: Authorization: KakaoAK {REST_API_KEY}
- 파라미터: query=서울특별시 중구 세종대로 110
응답에서 documents 배열의 첫 번째 항목에서 x(경도), y(위도) 값을 추출하면 돼요.
자동차 길찾기 API 호출
카카오 모빌리티의 자동차 길찾기 API를 호출하는 예시예요.
- 엔드포인트: GET https://apis-navi.kakaomobility.com/v1/directions
- 헤더: Authorization: KakaoAK {REST_API_KEY}
- 파라미터: origin=경도,위도 / destination=경도,위도 / waypoints(경유지, 선택)
응답으로는 소요 시간, 거리, 경로 좌표 배열(polyline) 등이 포함돼요. 이를 바탕으로 지도 위에 경로를 그리거나 소요 시간을 표시할 수 있어요.
응답 데이터 파싱
길찾기 API 응답에서 주요 필드는 다음과 같아요.
- duration: 예상 소요 시간 (초 단위)
- distance: 총 거리 (미터 단위)
- sections: 구간별 경로 정보
- guides: 안내 메시지 (좌회전, 직진 등)
- vertexes: 경로 좌표 배열 (지도 위에 경로선을 그릴 때 사용)
JavaScript API와 연동하기
카카오맵 JavaScript SDK 로드
웹 페이지에서 카카오맵을 표시하려면 JavaScript SDK를 HTML에 포함해야 해요.
- HTML head 태그에 다음 스크립트 추가: <script type=”text/javascript” src=”//dapi.kakao.com/v2/maps/sdk.js?appkey=YOUR_JAVASCRIPT_KEY”></script>
appkey에는 카카오 개발자 콘솔에서 발급받은 JavaScript 키를 입력해야 해요.
지도 위에 경로 표시
REST API로 얻은 경로 좌표(vertexes)를 카카오맵 JavaScript API를 이용해 지도 위에 폴리라인으로 표시하는 방식으로 경로를 시각화할 수 있어요. 출발지와 목적지 마커를 추가하고, 경로 좌표를 연결하는 선을 그리면 완성된 길찾기 지도가 만들어져요.
API 사용 시 주의사항
무료 사용량 제한
카카오 API는 무료 사용량이 제한되어 있어요. 일정 횟수를 초과하면 요금이 발생하거나 호출이 차단될 수 있어요. 개발·테스트 단계에서는 무료 할당량 내에서 사용하고, 상용 서비스라면 요금제를 확인하고 비용을 예산에 반영해야 해요.
도메인 등록 필수
웹에서 카카오 API를 사용하려면 개발자 콘솔에서 사용할 도메인을 등록해야 해요. 등록되지 않은 도메인에서 호출하면 오류가 발생해요. 개발 환경(localhost)도 별도로 등록해야 해요.
CORS 정책
REST API를 클라이언트 사이드(브라우저)에서 직접 호출하면 CORS 오류가 발생할 수 있어요. REST API는 서버 사이드에서 호출하고 결과를 클라이언트에 전달하는 방식이 안전해요. API 키가 노출되지 않도록 반드시 서버에서 처리하세요.
마치며
카카오맵 길찾기 API는 지도 서비스와 경로 탐색 기능을 자신의 서비스에 통합하려는 개발자들에게 강력한 도구예요. URL 스킴 방식은 간단하게 카카오맵 앱을 열어주는 데 유용하고, REST API는 서비스 내에서 직접 경로를 계산하고 표시하는 데 적합해요.
카카오 개발자 콘솔에서 API 키를 발급받고, 공식 문서(developers.kakao.com)를 참고하면서 단계적으로 구현해보세요. 무료 할당량과 요금 정책을 미리 파악하고 서비스 규모에 맞게 계획을 세우는 것도 중요해요!