KakaoNavi

KakaoNavi API is an API provided by KakaoNavi Service and provides the following functionalities.

  • Share Destination
    Share a destination via calling KakaoNavi application.
  • Navigation
    Request navigation to a destination via calling KakaoNavi application.

Contents

Before getting started

1. Refer to loginfree template and confirm that your app setting is not missing any requirement.

[kakao_strings.xml]

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

[AndroidManifest.xml]

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

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

Getting started

API requests are made with KakaonaviService. KakaonaviService achieves share/navigation functionalities by opening either Kakaonavi application or browser with intent and uri scheme; it opens the native application if installed or browser, otherwise.

KakaoNavi API uses an object of KakaonaviParams that contains every parameter you can provide to the API. Below section explains how you can configure these parameters for specific requests.

Configuring the parameters

Classes that define the parameters use their own builders to instantiate objects because they have a large number of optional parameters. Each class has a newBuilder method that accepts required parameters. You create a builder object by calling this static methhod and set additional optional parameters using their setters. Then, you call build() method to build the actual parameter object, which will be passed as arguments to a higher-level parameter object or the API call itself. Below lists various enum classes that describes options you can choose for the API.

Destination

Class that defines destination, which is a required parameter for KakaoNavi API.

Name Type Description Default Usage
name String Destination name (required) Share/Navigation
x Double Destination x (longitude, required) Share/Navigation
y Double Destination y (latitude, required) Share/Navigation
// Create a Destination object using Destination.Builder.
Destination destination = Destination.newBuilder("카카오 판교 오피스", 127.0083, 36.487785).build();

Class that defins optional parameters to KakaoNavi API. Share Destination API uses only coordType while all the other parameters are used by navigation API.

Name Type Description Default Usage
coordType CoordType Coordinate type katec Share/Navigation
vehicleType VehicleType Vehicle type FIRST Navigation
rpoption RpOption Route option FASTEST Navigation
startX Double Starting coordinates x Navigation
startY Double Starting coordinates y Navigation
startAngle Integer Start angle (0~359) -1 Navigation
userId String USER ID to distinguish users (used by KakaoTaxi) Navigation
returnUri String URI to be called when navigation terminates Navigation

CoordType

Enum class for coordinate types.

Name Value Description
WGS84 "wgs84" World Geodetic System 84 coordinates
KATEC "katec" Katec coordinates

VehicleType

Enum class for vehicle types.

Name Value Description
FIRST 1 First class (Sedan / Minivan / Small-sized truck)
SECOND 2 Second class (Medium-sized van / Medium-sized truck)
THIRD 3 Third class (Large van / Twin-axis large truck)
FOURTH 4 Fourth class (Tri-axis large truck)
FIFTH 5 Fifth class (Large truck with 4 or more axes)
SIXTH 6 Sixth class (Small car)
TWO_WHEEL 7 Two-wheeled vehicle

RpOption

Enum class for route options.

Name Value Description
FAST 1 Fastest route
FREE 2 Free route
SHORTEST 3 Shortest route
NO_AUTO 4 Exclude motorcar road
WIDE 5 Prioritize wide road
HIGHWAY 6 Prioritize Highway
NORMAL 8 Prioritize normal road

Create a NaviOptions object as below.

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

KakaonaviParams

Contains every parameter needed for calling KakaoNavi API. Destination is a required parameter for both Sharing Destination and Navigation while stops is an optional parameter for navigation. You instantiate a KakaonaviParams object using KakaonaviParams.Builder.

Name Type Description Usage
destination Destination Destination (required) Share/Navigation
naviOptions NaviOptions Optional Parameters (optional) Share/Navigation
stops List\ Stops (optional, up to three) Navigation
// KakaonaviParams object that does not include stops
KakaonaviParams params = KakaonaviParams.newBuilder(destination).setNaviOptions(options).build();

// KakaonaviParams object with 1 stop
List<Destination> viaLists = new ArrayList<Destination>();
viaLists.add(Destination.newBuilder("서초한빛삼성아파트", 126.5, 33.4));
KakaonaviParams params = KakaonaviParams.newBuilder(destination).setNaviOptions(options).setViaLists(viaLists).build();

Share Destination

KakaonaviService#requestShareDestination API를 호출합니다.

Name Type Description
activity Activity current activity of the application
params KakaonaviParams KakaonaviParams object

Below is a code snippet from the sample application that calls Share Destination API.

Destination destination = Destination.newBuilder("Kakao Pangyo Office", 127.0083, 36.487785).build();
KakaonaviParams params = KakaonaviParams.newBuilder(destination)
.setNaviOptions(NaviOptions.newBuilder().setCoordType(CoordType.WGS84).build()).build();

KakaonaviService.getInstance().shareDestination(KakaoNaviMainActivity.this, params);

Below is a screenshot of an activity from KakaoNavi application when you share a destination via KakaoNavi SDK. KakaoNavi Share Destination

You can call KakaonaviService#requestNaviGuide in order to get navigation to a destination via KakaoNavi application. Navigation API accepts up to three stops for navigation.

Name Type Description
activity Activity current activity of the application
params KakaonaviParams KakaonaviParams object

Below is a code snipeet from the sample application that calls Navigation API.

// Setting stops
List<Destination> viaLists = new ArrayList<Destination>();
viaLists.add(Destination.newBuilder("Seocho Hanbit Samsung APT", 126.5, 33.4).build());

final KakaonaviParams params = KakaonaviPrams.newBuilder(Destination.newBuilder("카카오 판교오피스", 127.0083, 36.487785).build())
  .setNaviOptions(NaviOptions.newBuilder().setCoordType(CoordType.WGS84).setStartX(126.5).setStartY(35.2).build())
  .setViaLists(viaLists).build();

KakaonaviService.getInstance().navigate(KakaonaviMainActivity.this, params);

Below are screenshots of activities from KakaoNavi application when you request navigation and when you request navigation with 1 stop location, respectively.

KakaoNavi Navigation KakaoNavi Navigation with Stops

RequestCode, which is a second parameter of KakaonaviService#requestShareDestination and KakaonaviService#requestNaviGuide is a value passed to startActivityForResult that will be called in order to open KakaoNavi application or browser. KakaoNavi SDK does not pass any data to onActivityResult and the only reason we accept the code is that developers can prevent any conflict between the request codes used by the SDK and the application themselves.


Last Modified : 2018-03-19