Android

이 문서는 Kakao SDK for Android(이하 Android SDK)를 사용한 카카오내비 API 구현 방법을 소개합니다.

시작하기 전에

모듈 설정

카카오내비 API는 카카오내비 모듈의 NaviClient가 제공합니다. 카카오내비 모듈은 ReactiveX 버전을 따로 제공하지 않으므로, 사용 중인 카카오 SDK 버전에 관계없이 동일하게 설정합니다. 모듈 설정을 참고하여 build.gradle(Module) 파일에 카카오내비 모듈인 v2-navi를 추가합니다.

카카오내비 앱 설치 여부 확인

카카오내비 API는 길 안내의 navigateIntent()와 목적지 공유의 shareDestinationIntent() 두 가지 주요 기능을 제공합니다.

navigateIntent() 또는 shareDestinationIntent()는 카카오내비 앱으로 목적지 공유 및 길 안내 기능을 실행하는 Intent를 반환합니다. 카카오내비 앱이 설치되어 있을 경우에는 앱을 호출하고, 그렇지 않을 경우에는 기본 브라우저로 설치 페이지를 엽니다.

사용자 기기에 카카오내비 앱이 설치되어 있는지 확인하려면 isKakaoNaviInstalled() API를 사용합니다. 다음은 카카오내비 앱 실행 여부를 출력해보는 예제입니다.

if (NaviClient.instance.isKakaoNaviInstalled(context)) {
    Log.i(TAG, "카카오내비 앱으로 길 안내 가능")
} else {
    Log.i(TAG, "카카오내비 미설치")
}

파라미터 구성하기

카카오내비 API 호출 시 필요한 파라미터들은 목적지 정보인 Location과 검색 조건을 정의한 NaviOption 객체에 담아 전달합니다.

Location

특정 장소를 표현하는 Location 클래스는 다음과 같이 구성돼 있습니다.

이름	타입	설명
name	String	장소 이름 "우리 집", "회사" 등
rpFlag	String	도착 링크 현재 미지원
x	Number	경도 좌표
y	Number	위도 좌표

NaviOption

길을 찾는 조건을 설정하는 NaviOption 클래스는 다음과 같이 구성돼 있습니다.

이름	타입	설명
coordType	CoordType	사용할 좌표계
vehicleType	VehicleType	차종(기본값: 카카오내비 앱에 설정된 차종)
rpOption	RpOption	경로 최적화 기준
routeInfo	Boolean	전체 경로 정보 보기 사용 여부
startX	Double	시작 위치의 경도 좌표 비고: 경로 검색 시 참고 정보이며, 길 안내 출발지는 사용자 현재 위치로 고정
startY	Double	시작 위치의 위도 좌표 비고: 경로 검색 시 참고 정보이며, 길 안내 출발지는 사용자 현재 위치로 고정
startAngle	Int	시작 차량 각도 0~359 사이의 값 비고: 경로 검색 시 참고 정보이며, 길 안내 출발지는 사용자 현재 위치로 고정
returnUri	String	길 안내의 전체 경로 보기 종료 시 호출될 URI

NaviOption의 모든 구성 요소는 선택적으로 지정 가능합니다. 하지만 중요한 구성 요소를 지정하지 않으면 카카오내비가 조건에 맞춰 장소와 길을 찾지 못하므로, 중요한 검색 조건들은 반드시 지정해야 합니다.

다음은 구성 요소별 클래스 정보입니다. Enum 클래스인 구성 요소는 지정된 값 중 하나만 사용할 수 있습니다.

Enum: CoordType

이름	설명
WGS84	World Geodetic System 84 좌표계
KATEC	Katec 좌표계 서버 기본값

Enum: VehicleType

이름	설명
FIRST	1종 승용차/소형승합차/소형화물차
SECOND	2종 중형승합차/중형화물차
THIRD	3종 대형승합차/2축 대형화물차
FOURTH	4종 3축 대형화물차
FIFTH	5종 4축이상 특수화물차
SIXTH	6종 경차
TWO_WHEEL	이륜차

Enum: RpOption

이름	설명
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) 기본 값으로 사용

길 안내하기

기본 정보

권한	사전 설정	카카오 로그인	사용자 동의	레퍼런스
-	플랫폼 등록	-	-	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)
    )
}

다음은 카카오내비 실행 후 길 안내를 시작한 화면입니다.

목적지 공유하기

기본 정보

권한	사전 설정	카카오 로그인	사용자 동의	레퍼런스
-	플랫폼 등록	-	-	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)
    )
}

다음은 카카오내비에서 목적지 공유하기를 실행한 화면입니다.

더 보기

Android SDK 다운로드Android SDK 레퍼런스outlink