이 문서는 Kakao SDK for Android(이하 Android SDK)를 사용한 카카오내비 API 구현 방법을 소개합니다.
카카오내비 API는 카카오내비 모듈의 NaviClient
가 제공합니다. 카카오내비 모듈은 ReactiveX 버전을 따로 제공하지 않으므로, 사용 중인 카카오 SDK 버전에 관계없이 동일하게 설정합니다. 모듈 설정을 참고하여 build.gradle.kts(Module) 파일에 카카오내비 모듈인 v2-navi
를 추가합니다.
카카오내비 API는 길 안내의 navigateIntent()
와 목적지 공유의 shareDestinationIntent()
두 가지 주요 기능을 제공합니다.
navigateIntent()
또는 shareDestinationIntent()
는 카카오내비 앱으로 목적지 공유 및 길 안내 기능을 실행하는 Intent
를 반환합니다. 카카오내비 앱이 설치되어 있을 경우에는 앱을 호출하고, 그렇지 않을 경우에는 기본 브라우저로 설치 페이지를 엽니다.
사용자 기기에 카카오내비 앱이 설치되어 있는지 확인하려면 isKakaoNaviInstalled()
API를 사용합니다. 다음은 카카오내비 앱 실행 여부를 출력해보는 예제입니다.
if (NaviClient.instance.isKakaoNaviInstalled(context)) {
Log.i(TAG, "카카오내비 앱으로 길 안내 가능")
} else {
Log.i(TAG, "카카오내비 미설치")
}
권한 | 사전 설정 | 카카오 로그인 | 동의항목 | 레퍼런스 |
---|---|---|---|---|
- | 플랫폼 등록 | - | - | navigateIntent() |
길 안내는 사용자의 현재 위치로부터 지정한 목적지까지의 경로를 카카오내비로 안내하는 기능입니다. NaviClient
의 navigateIntent()
를 호출해 Intent
를 반환 받아 실행하도록 구현합니다.
navigateIntent()
호출 시 목적지 정보를 담은 Location, 검색 조건을 담은 NaviOption 객체를 전달해야 합니다. NaviOption
에는 원하는 검색 조건만 지정하여 요청할 수 있습니다.
startX
, startY
, startAngle
파라미터를 사용해 경로 검색 시 참고할 출발 지점을 지정할 수 있습니다. 그러나 길 안내 시에는 사용자의 현재 위치로부터 목적지까지의 안내만을 제공하며, 별도의 출발 지점을 지정할 수는 없습니다.
다음은 길 안내 예제입니다.
// 카카오내비 앱으로 길 안내
if (NaviClient.instance.isKakaoNaviInstalled(requireContext())) {
// 카카오내비 앱으로 길 안내 - WGS84
startActivity(
NaviClient.instance.navigateIntent(
Location("카카오 판교오피스", "127.108640", "37.402111"),
NaviOption(coordType = CoordType.WGS84)
)
)
} else {
// 카카오내비 설치 페이지로 이동
startActivity(
Intent(
Intent.ACTION_VIEW,
Uri.parse(Constants.WEB_NAVI_INSTALL)
).addFlags(Intent.FLAG_ACTIVITY_NEW_TASK or Intent.FLAG_ACTIVITY_CLEAR_TOP)
)
}
경유지 목록 설정이 가능합니다. 각 경유지 정보를 Location
객체에 담고, 요청 시 viaList
파라미터로 경유지 Location
의 리스트(List)를 전달합니다.
if (NaviClient.instance.isKakaoNaviInstalled(requireContext())) {
// 카카오내비 앱으로 길 안내 - WGS84 - 경유지 추가
startActivity(
NaviClient.instance.navigateIntent(
Location("카카오 판교오피스", "127.108640", "37.402111"),
NaviOption(coordType = CoordType.WGS84),
// 경유지 목록 설정
listOf(
Location("판교역 1번출구", "127.111492", "37.395225")
)
)
)
} else {
// 카카오내비 설치 페이지로 이동
startActivity(
Intent(
Intent.ACTION_VIEW,
Uri.parse(Constants.WEB_NAVI_INSTALL)
).addFlags(Intent.FLAG_ACTIVITY_NEW_TASK or Intent.FLAG_ACTIVITY_CLEAR_TOP)
)
}
다음은 카카오내비 실행 후 길 안내를 시작한 화면입니다.
Android SDK 2.8.4부터 카카오내비 앱 미설치 시 웹에서 길 안내를 실행하는 기능을 더 이상 제공하지 않습니다. 카카오내비 앱이 설치돼 있지 않은 경우에는 설치 페이지로 이동합니다. 이전 버전에서 제공하는 웹 길 안내 기능 또한 추후 제공 종료될 예정이므로, 최신 버전 업데이트를 권장합니다.
권한 | 사전 설정 | 카카오 로그인 | 동의항목 | 레퍼런스 |
---|---|---|---|---|
- | 플랫폼 등록 | - | - | shareDestinationIntent() |
목적지 공유하기는 카카오내비에서 지정한 목적지 정보를 공유할 수 있는 화면을 보여주는 기능입니다. NaviClient
의 shareDestinationIntent()
를 호출해 Intent
를 반환 받아 실행하도록 구현합니다.
shareDestinationIntent()
호출 시 목적지 정보를 담은 Location, 검색 조건을 담은 NaviOption 객체를 전달해야 합니다. NaviOption
에는 원하는 검색 조건만 지정하여 요청할 수 있습니다.
startX
, startY
, startAngle
파라미터를 사용해 경로 검색 시 참고할 출발 지점을 지정할 수 있습니다. 그러나 길 안내 시에는 사용자의 현재 위치로부터 목적지까지의 안내만을 제공하며, 별도의 출발 지점을 지정할 수는 없습니다.
다음은 목적지 공유하기 예제입니다.
if (NaviClient.instance.isKakaoNaviInstalled(requireContext())) {
// 카카오내비 앱으로 목적지 공유하기 - WGS84
startActivity(
NaviClient.instance.shareDestinationIntent(
Location("카카오 판교오피스", "127.108640", "37.402111"),
NaviOption(coordType = CoordType.WGS84)
)
)
} else {
// 카카오내비 설치 페이지로 이동
startActivity(
Intent(
Intent.ACTION_VIEW,
Uri.parse(Constants.WEB_NAVI_INSTALL)
).addFlags(Intent.FLAG_ACTIVITY_NEW_TASK or Intent.FLAG_ACTIVITY_CLEAR_TOP)
)
}
경유지 목록 설정이 가능합니다. 각 경유지 정보를 Location
객체에 담고, 요청 시 viaList
파라미터로 경유지 Location
의 리스트(List)를 전달합니다.
// 카카오내비 앱으로 목적지 공유하기 - 경유지 추가
if (NaviClient.instance.isKakaoNaviInstalled(requireContext())) {
// 카카오내비 앱으로 목적지 공유하기 - WGS84
startActivity(
NaviClient.instance.shareDestinationIntent(
Location("카카오 판교오피스", "127.108640", "37.402111"),
NaviOption(coordType = CoordType.WGS84),
// 경유지 목록 설정
listOf(
Location("판교역 1번출구", "127.111492", "37.395225")
)
)
)
} else {
// 카카오내비 설치 페이지로 이동
startActivity(
Intent(
Intent.ACTION_VIEW,
Uri.parse(Constants.WEB_NAVI_INSTALL)
).addFlags(Intent.FLAG_ACTIVITY_NEW_TASK or Intent.FLAG_ACTIVITY_CLEAR_TOP)
)
}
다음은 카카오내비에서 목적지 공유하기를 실행한 화면입니다.
카카오내비 API 호출 시 필요한 파라미터들은 목적지 정보인 Location
과 검색 조건을 정의한 NaviOption
객체에 담아 전달합니다.
특정 장소를 표현하는 Location
클래스는 다음과 같이 구성돼 있습니다.
이름 | 타입 | 설명 |
---|---|---|
name | String |
장소 이름 "우리 집", "회사" 등 |
rpFlag | String |
도착 링크 현재 미지원 |
x | Number |
경도 좌표 |
y | Number |
위도 좌표 |
길을 찾는 조건을 설정하는 NaviOption
클래스는 다음과 같이 구성돼 있습니다.
이름 | 타입 | 설명 |
---|---|---|
coordType | CoordType |
사용할 좌표계 |
vehicleType | VehicleType |
차종(기본값: 카카오내비 앱에 설정된 차종) |
rpOption | RpOption |
경로 최적화 기준 |
routeInfo | Boolean |
전체 경로 정보 보기 사용 여부 |
startX | Double |
시작 위치의 경도 좌표 비고: 경로 검색 시 참고 정보이며, 길 안내 출발지는 사용자 현재 위치로 고정 |
startY | Double |
시작 위치의 위도 좌표 비고: 경로 검색 시 참고 정보이며, 길 안내 출발지는 사용자 현재 위치로 고정 |
startAngle | Int |
시작 차량 각도 0~359 사이의 값 비고: 경로 검색 시 참고 정보이며, 길 안내 출발지는 사용자 현재 위치로 고정 |
returnUri | String |
길 안내의 전체 경로 보기 종료 시 호출될 URI |
NaviOption
의 모든 구성 요소는 선택적으로 지정 가능합니다. 하지만 중요한 구성 요소를 지정하지 않으면 카카오내비가 조건에 맞춰 장소와 길을 찾지 못하므로, 중요한 검색 조건들은 반드시 지정해야 합니다.
이름 | 설명 |
---|---|
WGS84 | World Geodetic System 84 좌표계 |
KATEC | Katec 좌표계 서버 기본값 |
이름 | 설명 |
---|---|
FIRST | 1종 승용차/소형승합차/소형화물차 |
SECOND | 2종 중형승합차/중형화물차 |
THIRD | 3종 대형승합차/2축 대형화물차 |
FOURTH | 4종 3축 대형화물차 |
FIFTH | 5종 4축이상 특수화물차 |
SIXTH | 6종 경차 |
TWO_WHEEL | 이륜차 |
이름 | 설명 |
---|---|
FAST | 가장 빠른 경로(Fastest route) |
FREE | 무료 도로(Free route) |
SHORTEST | 가장 짧은 경로(Shortest route) |
NO_AUTO | 자동차 전용 도로 제외(Exclude motorway) |
WIDE | 큰길 우선(Wide road first) |
HIGHWAY | 고속도로 우선(Highway first) |
NORMAL | 일반 도로 우선(Normal road first) |
RECOMMENDED | 추천 경로(Recommended route) 기본 값으로 사용 |