카카오내비

카카오내비 API는 카카오내비 서비스에서 제공하는 API를 말하며, 다음과 같은 기능을 제공합니다.

  • 목적지 공유
    카카오내비 앱을 호출하여 목적지를 공유합니댜.
  • 목적지 길안내
    카카오내비 앱을 호출하여 목적지까지 길안내를 실행합니다.

차례

시작하기 전에

1. 사용할 앱의 build.gradle 파일에 아래와 같이 카카오내비 모듈을 설정합니다.

project.KAKAO_SDK_VERSION 에는 sdk 버전을 명시합니다. gradle 지원은 1.0.36부터 지원되지만 최신 패키지 구조가 변경된 1.1.0버전 이상의 gradle project를 사용하시길 권장합니다.

dependencies {
    compile group: 'com.kakao.sdk', name: 'kakaonavi', version: project.KAKAO_SDK_VERSION
}

2. Kakao-계정-로그인이-필요없는-앱설정을 참고하여 빠진 부분이 없는지 확인합니다.

[kakao_strings.xml]

<resources>
    <string name="kakao_app_key">AAAAAAAAAAAAAAAAAAAAAA</string>
</resources>

카카오내비 SDK는 카카오내비 앱이 설치되어 있지 않을 때 기본적으로 웹뷰를 사용하여 길안내를 시작합니다. 이 기능을 사용하기 위해서는 앱에 위치 권한을 줘야 합니다.

[AndroidManifest.xml]

<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />

<application
    ...
    <meta-data
       android:name="com.kakao.sdk.AppKey"
       android:value="@string/kakao_app_key" />
    ...
 </application>

만약 웹뷰를 사용하기 싫거나 앱에 위치 권한을 사용하는 것이 부담스럽다면 AndroidManifest.xml에 다음과 같이 위치 권한을 빼주시고 "com.kakao.sdk.kakaonavi.useWebView" 라는 값을 false로 지정해 주시면 됩니다.

[AndroidManifest.xml]

<uses-permission android:name="android.permission.INTERNET" />
<application
    ...
    <meta-data
       android:name="com.kakao.sdk.AppKey"
       android:value="@string/kakao_app_key" />
    <meta-data
      android:name="com.kakao.sdk.kakaonavi.useWebView"
      android:value="false" />
    ...
 </application>

시작하기

API 요청은 KakaoNaviService를 이용합니다. KakaoNaviService는 인텐트 호출을 통하여 카카오내비 앱 또는 브라우저를 구동하여 목적지 공유/길안내 기능을 실행합니다. 카카오내비 앱이 설치되어 있을 경우에는 앱을 호출하고 그렇지 않을 경우에는 기본 브라우저로 카카오내비의 웹버전을 엽니다.

카카오내비 API는 카카오내비 앱을 호출할 때, 제공되는 모든 파라미터들 채워넣을 수 있는 KakaoNaviParams 클래스의 객체를 사용합니다. 아래에는 이 API가 제공하는 다양한 파라미터들을 어떻게 구성할 수 있는지 설명하겠습니다.

파라미터 구성

기본적으로 파라미터를 표현하는 클래스들은 파라미터의 개수가 많기 때문에 빌더 객체를 사용하여 만들도록 구성되어 있습니다. 각 파라미터 클래스들은 필수 파라미터를 포함하는 newBuilder라는 메소드를 가지고 있습니다. 이 메소드를 사용하여 필수 파라미터들을 채우고 있는 빌더 객체를 만들고 선택적 파라미터들은 setter를 통하여 구성하여 준 다음 build() 메소드를 통하여 파라미터 객체를 만듭니다. 아래에는 더 자세한 파라미터 클래스들의 형태와 옵션들을 정의하는 다양한 enum 클래스들을 설명합니다.

Location

카카오내비 API의 필수 파라미터인 목적지를 정의하는 class

Name Type Description Default Usage
name String 목적지 이름 (필수) 공유/길인내
x Double 목적지 x (경도, 필수) 공유/길인내
y Double 목적지 y (위도, 필수) 공유/길인내
// Location.Builder를 사용하여 Location 객체를 만든다.
Location destination = Location.newBuilder("카카오 판교 오피스", 127.10821222694533, 37.40205604363057).build();

카카오내비 API의 선택 파라미터들을 정의하는 class. 이 클래삭 포함하는 모든 파라미터들은 선택적입니다. 목적지 공유에는 coordType만 쓰이고 나머지 파라미터들은 목적지 길안내에 쓰입니다.

Name Type Description Default Usage
coordType CoordType 좌표 타입 katec 공유/길안내
vehicleType VehicleType 차종 FIRST 길안내
rpOption RpOption 경로 옵션 FASTEST 길안내
routeInfo boolean 전체경로보기 여부 false 길안내
startX Double 시작좌표 x 길안내
startY Double 시작좌표 y 길안내
startAngle Integer 시작 앵글 (0~359). 앵글을 설정하지 않을 경우 : -1 길안내
userId String 길안내 유저 구분을 위한 USER ID (현재 택시에서 사용) 길안내
returnUri String 길안내 종료(전체 경로보기시 종료) 후 호출 될 URI 길안내

CoordType

좌표 타입을 정의한 Enum class

Name Value Description
WGS84 "wgs84" World Geodetic System 84 좌표계
KATEC "katec" Katec 좌표계

VehicleType

차종을 정의한 Enum class

Name Value Description
FIRST 1 1종 (승용차/소형승합차/소형화물화)
SECOND 2 2종 (중형승합차/중형화물차)
THIRD 3 3종 (대형승합차/2축 대형화물차)
FOURTH 4 4종 (3축 대형화물차)
FIFTH 5 5종 (4축이상 특수화물차)
SIXTH 6 6종 (경차)
TWO_WHEEL 7 이륜차

RpOption

경로 옵션을 정의한 Enum class

Name Value Description
FAST 1 빠른길
FREE 2 무료도로
SHORTEST 3 최단거리
NO_AUTO 4 자동차전용제외
WIDE 5 큰길우선
HIGHWAY 6 고속도로우선
NORMAL 8 일반도로우선

다음과 같이 NaviOptions 객체를 만듭니다.

NaviOptions options = NaviOptions.newBuilder().setCoordType(CoordType.WGS84).setVehicleType(VehicleType.FIRST).setRpOption(RpOption.SHORTEST).build();

KakaoNaviParams

카카오내비 API 호출을 위한 모든 파라미터들을 담고 있는 class. Destination은 목적지 공유와 길안내에 모두 필수적인 파라미터이고 Stops는 목적지 길안내에만 제공되는 선택적 파라미터입니다. 위에 언급된 파라미터들로 KakaoNaviParams.Builder 객체를 생성하고 API 호출 시에는 이 객체를 직접 넘겨주게 됩니다.

Name Type Description Usage
destination Location 목적지 (필수) 공유/길안내
naviOptions NaviOptions 옵션 (선택) 공유/길안내
stops List<Location> 경유지 (선택, 세개까지 가능) 길안내
// 경유지를 포함하지 않는 KakaoNaviParams.Builder 객체
KakaoNaviParams.Builder builder = KakaoNaviParams.newBuilder(destination).setNaviOptions(options);

// 경유지를 1개 포함하는 KakaoNaviParams.Builder 객체
List<Location> viaList = new ArrayList<Location>();
viaList.add(Location.newBuilder("서서울호수공원", 126.8322289016308, 37.528495607451205).build());
KakaoNaviParams.Builder builder = KakaoNaviParams.newBuilder(destination).setNaviOptions(options).setViaList(viaList);

KakaoNaviParams params = builder.build();

목적지 공유

KakaoNaviService#shareDestination API를 호출합니다.

Name Type Description
activity Activity 카카오내비 앱의 액티비틀 호출하는 현재 앱의 activity
params KakaoNaviParams KakaoNaviParams 객체

다음은 목적지 공유를 호출하는 예제입니다.

...

Location destination = Location.newBuilder("카카오 판교 오피스", 127.10821222694533, 37.40205604363057).build();
KakaoNaviParams.Builder builder = KakaoNaviParams.newBuilder(destination)
.setNaviOptions(NaviOptions.newBuilder().setCoordType(CoordType.WGS84).build());

KakaoNaviService.shareDestination(KakaoNaviMainActivity.this, builder.build());

다음은 SDK를 통하여 목적지를 공유하였을 때 실행되는 카카오내비의 activity입니다.

카카오내비 목적지 공유

목적지 길안내

KakaoNaviService#navigate API를 호출합니다. 경유지를 세개까지 지정할 수 있습니다.

Name Type Description
activity Activity 카카오내비 앱의 액티비틀 호출하는 현재 앱의 activity
params KakaoNaviParams KakaoNaviParams 객체

다음은 목적지 길안내를 호출하는 예제입니다.

...

// 경유지 설정
List<Location> viaList = new ArrayList<Location>();
viaList.add(Location.newBuilder("서서울호수공원", 126.8322289016308, 37.528495607451205).build());

final KakaoNaviParams.Builder builder = KakaoNaviParams.newBuilder(Location.newBuilder("카카오 판교오피스", 127.10821222694533, 37.40205604363057).build()).setNaviOptions(NaviOptions.newBuilder().setCoordType(CoordType.WGS84).setStartX(126.5).setStartY(35.2).build()).setViaList(viaList);

KakaoNaviService.navigate(KakaoNaviMainActivity.this, builder.build());

다음은 각각 SDK를 통하여 길안내를 실행하였을 때 안내가 시작된 화면과 경유지를 지정하여 길안내를 시작한 화면입니다.

카카오내비 목적지 길안내 카카오내비 경유지


Last Modified : 2017-07-28