Android NavKit API User Guide

Navigation Class

Navigation class is the main class of NavKit and acts as the controller of navigation. It creates and controls the life cycle of a navigation session and other major navigation related operations, such as pause/stop, set active route, play announcement, and so on.

The following table describes the major functions and commonly used methods in the Navigation class.

Table 1. Navigation Class Methods
Method	Description
`updatePosition(Location location)`	Updates the navigation session with the location. The first position update triggers a route generation
`startPlanRoute(Location origin)`	Starts a plan route from the origin location
`pauseSession()`	Pauses the current navigation session
`resumeSession()`	Resumes the current navigation session
`stopSession()`	Stops the current navigation session
`setActiveRoute(RouteInformation route)`	Selects/activates the route for the current navigation session
`announce()`	Triggers the announcement for the current step within the current session. It has overloaded parameters for the specific maneuver along with the route
`recalculate()`	Recalculates the current route session
`doDetour()`	Calculates a detour route from the current position
`cancelDetour()`	Cancels the detour request

Navigation Event Listeners

The four sets of navigation events in the Android NavKit are described in the following table.

Table 2. Navigation Events
Navigation Event	Description
Session Events	Notifies the subscriber about route states like, new route received, route generation progress, end of route, and so on
Navigation Events	Notifies the subscriber about user position updates on the route like, maneuver remaining distance, trip remaining distance, current road name, and so on
Announcement Events	Notifies the subscriber about announcements which should be played based on the current user position
Traffic Events	Notifies the subscriber about the traffic alerts and traffic changes during navigation

The listeners should be registered to the navigation session in order to receive any of the event notifications. The following table describes all the event listeners.

Table 3. Navigation Event Listeners
Navigation Event Listener	Description
`Navigation.addAnnouncementListener` `(AnnouncementListener listener)`	Receives notifications when an announcement needs to be played
`Navigation.addLaneGuidanceListener` `(LaneGuidanceListener listener)`	Receives lane guidance enabled/disabled notifications
`Navigation.addManeuverUpdateListener` `(ManeuverUpdateListener listener)`	Receives notifications associated with a maneuver change
`Navigation.addNavEventListener(NavEventListener listener)`	Receives notifications associated with the navigation session, which are not directly linked to the position or maneuver updates
`Navigation.addNavigationUpdateListener` `(NavigationUpdateListener listener)`	Receives notifications on position changes with respect to the entire route and the current maneuver
`Navigation.addPositionUpdateListener` `(PositionUpdateListener listener)`	Receives notifications that are generated whenever the position changes
`Navigation.addRoadSignListener(RoadSignListener listener)`	Receives road sign enabled/disabled notifications
`Navigation.addSessionListener(SessionListener listener)`	Receives session related notifications
`Navigation.addSpeedLimitListener (SpeedLimitListener listener)`	Receives speed limit enabled/disabled notifications
`Navigation.addTrafficListener(TrafficListener listener)`	Receives traffic notifications

Note	All events are sent within the main Android User Interface (UI) thread, which allows you to make instantaneous UI updates.

SessionListener

SessionListener is the basic listener for a Navigation session and provides navigation session related notifications like route updates, errors and so on. The following code snippet registers the SessionListener to Navigation.

navigation.addSessionListener(new SessionListener() {

    // SessionListener interface implementation
    ...
}

The following table describes the SessionListener events.

Table 4. SessionListener Events
Event	Description
`void offroute()`	Informs the subscriber that the locations being received by the navigation session are not considered on route to the destination
`void onroute()`	Informs the subscriber that the locations being received by the navigation session are considered on route to the destination
`void routeReceived(int reason, RouteInformation[] routeInformations)`	Provides the list of possible routes for the current navigation session. When navigation succeeds, it generates a callback to get the route information
`void routeRequested(int reason)`	Informs the subscriber that new route is requested with a reason. When requesting navigation, it generates a callback
`void routeProgress(int reason)`	Provides the route generation progress
`void routeError(LTKException e)`	Indicates that an error occurred and that the navigation session is no longer valid
`void routeFinish()`	Informs the subscriber that the current navigation session has ended. On reaching the destination, a callback gets generated
`void routeUpdating()`	Informs the subscriber that route is going to be updated by recalculation

NavigationUpdateListener

NavigationUpdateListener provides navigation related notifications like current road name, remaining trip distance and so on. It is triggered only after navigation route activation. The following code snippet registers the NavigationUpdateListener to Navigation.

navigation.addNavigationUpdateListener(new NavigationUpdateListener() {

    // NavigationUpdateListener interface implementation
    ...
}

The following table describes the NavigationUpdateListener events.

Table 5. NavigationUpdateListener Events
Event	Description
`void currentRoadName(String primaryName, secondaryName)`	Provides updates to the current road name
`void maneuverExitNumber(String exitNumber)`	Provides updates to the current maneuver exit number
`void maneuverImageId(String imageId)`	Provides maneuver image ID
`void maneuverPoint(Coordinates point)`	Provides turn point coordinates
`void maneuverRemainingDelay(int delay)`	Provides updates to the remaining maneuver delay, in seconds
`void maneuverRemainingDistance(double distance)`	Provides updates to the remaining distance to next maneuver in meters
`void maneuverRemainingTime(int time)`	Provides updates to the remaining maneuver time in seconds
`void maneuverType(String type)`	Provides updates to the current maneuver type
`void nextRoadName(String primaryName, String secondaryName)`	Provides updates to the next road name
`void positionUpdated(Coordinates coordinates, double speed, int heading)`	Notifies that the position on the route has been changed
`void stackTurnImageTTF(String stackImageTTF)`	Provides stack turn image text in True Type Font (TTF) format
`void tripRemainingDelay(int delay)`	Provides updates to the remaining trip delay. Using this method, the current remaining delay of navigation can be known
`void tripRemainingDistance(double distance)`	Provides updates to the remaining trip distance. Using this method, the current remaining distance of navigation can be obtained
`void tripRemainingTime(int time)`	Provides updates to the remaining trip time. Using this method, the current remaining navigation time can be obtained
`void updateManeuverList(ManeuverList maneuvers)`	Notifies when maneuver list gets updated. Using this method, the remaining maneuver list can be obtained

AnnouncementListener

This listener provides the navigation announcement notifications. The following code snippet registers the AnnouncementListener to Navigation.

navigation.addAnnouncementListener(new AnnouncementListener() {
    // AnnouncementListener interface implementation
    ...
}

It has a single event which is described as follows.

void announce(AnnouncementInformation announcement) - Informs the subscriber that an announcement needs to be played.

RouteInformation Class

The RouteInformation class provides details of the received route after route calculation, which is obtained through the SessionListener.routeReceived() as shown in the following code snippet.

@Override
public void routeReceived(int reason, RouteInformation[] routeInfos) {
    // List of routes as RouteInformation array
    RouteInformation routeInformation = routeInfos[0];
}

RouteInformation class has the methods to get information about the origin, destination, distance, time, and so on, described in the following table.

Table 6. RouteInformation Class Methods
Method	Description
`Place getOrigin()`	Gets route origin place
`Place getDestination()`	Gets route destination place
`double getTime()`	Gets total route time in seconds
`double getDistance()`	Gets total route distance in meters
`double getDelay()`	Gets total route delay time in seconds
`double getRemainingTime()`	Gets the active route’s remaining time in seconds
`double getRemainingDistance()`	Gets the active route’s remaining distance in meters
`ManeuverList getManeuverList()`	Gets maneuver list
`Coordinates[] getPolyline()`	Returns the coordinates on route polyline for the entire route
`String getRouteDescription()`	Gets description of route traffic segments
`String getTrafficColor()`	Returns the overall traffic color based on the delay
`List<TrafficEvent> getTrafficEvents()`	Returns traffic events
`short getRouteError()`	Gets route error code
`byte[] getVoiceFile(String name)`	Returns the data corresponding to the given voice name

ManeuverList Class

The ManeuverList class returns a list of navigation maneuvers. It is received through getManeuverList method of the RouteInformation object as shown in the following code snippet.

@Override
public void routeReceived(int reason, RouteInformation[] routeInfos) {
    ManeuverList maneuverList = routeInfos[0].getManeuverList();
}

The following table describes the methods available in ManeuverList class.

Table 7. ManeuverList Class Methods
Method	Description
`Place getOrigin()`	Get maneuver origin
`Place getDestination()`	Gets maneuver destination place
`double getTotalDistance()`	Returns the total trip distance
`double getTotalTripTime()`	Returns total actual time for maneuvers list
`int getNumberOfManeuvers()`	Returns number of maneuvers
`Maneuver getManeuver(int index)`	Returns maneuver by the given index
`double getTotalDelay()`	Returns total delay time for maneuvers list
`BoundingBox routeBoundingBox()`	Returns BoundingBox that contains all of the maneuvers

Maneuver Class

The Maneuver class represents the information of an individual navigation maneuver. It is received through getManeuver method of the ManeuverList object as shown in the following code snippet.

ManeuverList maneuverList = routeInformations[0].getManeuverList();
Maneuver maneuver = maneuverList.getManeuver(0);

The following table describes the methods which obtain maneuver details.

Table 8. Maneuver Class Methods
Method	Description
`Coordinates getPoint()`	Gets point coordinates
`Coordinates[] getPolyline()`	Returns the coordinates on route polyline for this maneuver
`String getCurrentRoadPrimaryName()`	Returns primary street name of current road
`String getCurrntRoadSecondaryName()`	Returns secondary street name of current road
`String getPrimaryStreet()`	Returns primary street
`String getSecondaryStreet()`	Returns secondary description
`double getDistance()`	Returns distance
`double getSpeed()`	Returns speed
`double getTime()`	Returns the maneuver actual time
`String getDescription()`	Returns maneuver description
`String getCommand()`	Gets the command
`String getRoutingIcon()`	Gets ID of routing icon to use for the maneuver
`double getTrafficDelay()`	Returns the maneuver delay time
`List<TrafficEvent> getTrafficEvents()`	Returns traffic events

Supported Maneuvers

The following table describes all the supported maneuvers in Android NavKit SDK.

Table 9. Supported Maneuvers
Command	Description	Usage	LG Font	NG Font	Example
DT.L , DT.R	Destination	Destination	Y	N	Your destination is on the left/right
ER.L , ER.R	Take ramp	Highway	N	N	Take ramp on the left
EX.L , EX.R	Exit highway	Highway	Y	N	Take exit 13A on the left
KH.L , KH.R	Keep (highway version)	Highway	Y	N	In 1 ½ miles take I-405
KS.L , KS.R	Keep (normal road version)	Normal	Y	Y	Get ready to keep to the right at the fork and take Main street
MR.L , MR.R	Merge	Highway	Y	N	Merge {highway} on the left
SH.L , SH.R	Stay (highway version)	Highway	Y	Y	In 2 ½ miles continue on I-5
BE.L , BE.R	Cross bridge	Normal	Y	N	—
EC.L , EC.R	Enter country	Normal	Y	N	In 5 miles you will enter Canada
EN.L , EN.R	Enter highway	Normal	Y	Y	Get ready to take the ramp straight ahead to I-5
FE.	Enter ferry	Normal	Y	N	Get ready to take the Avalon ferry
FX.	Exit ferry	Normal	N	N	Exit the ferry
KP.L , KP.R	Keep (current version which will be deprecated)	Normal	Y	Y	Get ready to keep right onto Main street
NC.	Name change	Normal	Y	N	Not used in announcements
NR.L , NR.R	Enter private road	Normal	Y	Y	Enter private on the left
OR.	Origin (startup case)	Normal	Y	N	Not used in announcements
PE.	Continue by foot	Normal	Y	N	Get ready to find parking then continue by foot to Main street
RE.	Enter roundabout	Normal	Y	N	Get ready to take the 4th exit at the roundabout onto Main street
RT.	Continue straight through roundabout	Normal	Y	N	In 1 mile continue straight through the roundabout onto Main street
RX.N	Exit traffic circle, where N represents the exit number	Normal	Y	N	Not used in announcements
ST.L , ST.R	Stay (normal version)	Normal	Y	Y	In 1 ¼ miles stay on Main street
TE.L , TE.R	Enter tunnel	Normal	N	N	—
TR.L , TR.R , TR.SL , TR.SR , TR.HL , TR.HR	Turn, slight turn, hard turn	Normal	Y	Y	Now turn right
UT.	U-turn	Normal	Y	N	Make the next legal U-turn
SC.S	Speed camera	Other	N	N	—
TC.S	Traffic congestion	Other	N	N	—
TL.S	Traffic incident	Other	N	N	—
EE.L , EE.R	Take escalator	Pedestrian	Y	N	Take escalator on the left
ES.L , ES.R	Take stairs	Pedestrian	Y	N	Take stairs on the left

AnnouncementInformation

AnnouncementInformation class provides audio data to be played. It is comprised of both audio files and audio text to be fed to the Text to Speech (TTS) engine. The following code snippet shows a sample method to play an announcement using Android TTS.

private TextToSpeech tts;
private void playAnnouncement(final AnnouncementInformation announcement) {
    tts = new TextToSpeech(this, new TextToSpeech.OnInitListener() {
        @Override
        public void onInit(int status) {
            if (status == TextToSpeech.SUCCESS) {
                tts.speak(announcement.getText(),
                        TextToSpeech.QUEUE_ADD, null);
            }
        }
    });
    tts.setLanguage(new Locale(ltkContext.getLanguage(),
            ltkContext.getCountryCode()));
}

Selecting the Route

Multiple routes are returned along with the primary route if alternative route has been enabled by setting setMultipleRoutes(true) in the navigation Preference class, through the SessionListener.routeReceived(). After receiving the routes, you can activate a single route from the available routes.

The following code snippet activates the first route as the current navigation route, from the available routes.

@Override
public void routeReceived(int reason, RouteInformation[] routeInfos) {
    if (routeInfos != null && routeInfos.length > 0) {
        navigation.setActiveRoute(routeInfos[0]);
    }
}

Off-Route Processing

A Navigation session is considered “off route” when the location being received is not considered to be “on route” to the destination. In this situation, the SessionListener.offroute() event is sent to the subscriber and NavKit starts route recalculation automatically. SessionListener.routeReceived() is triggered once a new route is received.

navigation.addSessionListener(new SessionListener() {

    @Override
    public void offroute() {
        // Navigation is offroute, show off-route notification to user
    }

    @Override
    public void routeReceived(int reason, RouteInformation[] routeInformations) {
        // New routes received
    }

    // Other SessionListener method implementations
    ...
}

Error Codes

NavKit will display different error codes if there is an occurrence of an error during navigation session initiation or progress.

LTKException

The error codes are thrown through SessionListener.routeError() as shown in the following code snippet.

public void routeError(LTKException exception) {
    if (exception != null) {
        int errorCode = exception.getErrorCode();
    }
}

The following table describes the navigation related LTKException codes.

Table 10. LTKException Codes
Error	Description
`LTK_NETWORK_ERROR2000`	The request failed for an unknown reason
`LTK_NETWORK_ERROR2001`	An error response was received from the server
`LTK_NETWORK_ERROR2002`	No response was received from the server within the allotted time
`LTK_NETWORK_ERROR2003`	An unknown low-level error was generated by the app
`LTK_NETWORK_ERROR2004`	An error occurred trying to connect to the server
`LTK_NETWORK_WRITE_ERROR`	Failed to write to a network socket
`LTK_NETWORK_READ_ERROR`	Failed to read from a network socket
`LTK_SERVER_ERROR4000`	Unable to load template library
`LTK_SERVER_ERROR4001`	Malformed packet
`LTK_SERVER_ERROR4002`	Malformed Template Packet System (TPS) document
`LTK_SERVER_ERROR4003`	Internal server error
`LTK_SERVER_ERROR4010`	Requested feature is unsupported
`LTK_SERVER_ERROR4014`	Unsupported vehicle type
`LTK_SERVER_ERROR4015`	Unsupported avoid element
`LTK_SERVER_ERROR4016`	Database error
`LTK_SERVER_ERROR4017`	User database error
`LTK_SERVER_ERROR4020`	Unable to process request
`LTK_SERVER_ERROR4021`	Too busy to process request
`LTK_SERVER_ERROR4022`	Unable to contact external server
`LTK_SERVER_ERROR4030`	Value specified in request is not valid
`LTK_SERVER_ERROR4031`	Latitude or longitude is out of range
`LTK_SERVER_ERROR` `_QUERY_LIMIT_REACHED`	The maximum daily queries limit for this API Key has been reached
`LTK_SERVER_ERROR_INVALID_API_KEY`	The specified API Key is not valid
`LTK_SERVER_ERROR_MDN_LIMIT_REACHED`	The maximum number of users for this API Key has been reached
`LTK_SERVER_FEATURE_NOT_AVAILABLE`	Feature not available in this country
`LTK_SERVER_FEATURE_NOT_SUPPORTED`	Feature not supported

RouteErrorCode

Navigation could be returned successful in SessionListener.routeReceived(), but the route returned or the maneuver list could be null. In such scenarios, the route errors can be retrieved from the RouteInformation object as shown in the following code snippet.

public void routeReceived(int reason, RouteInformation[] routes) {
    if (routes[0].getManeuverList() == null ||
            routes[0].getManeuverList().getNumberOfManeuvers() == 0) {
        if(routes[0].getRouteError() == RouteErrorCode.ROUTE_NONE){
            // Show No Route
        }
    }
}

The following table describes the available route errors.

Table 11. Route Errors
Error	Description
`ROUTE_NONE`	No error/No route
`LTK_ROUTE_ERROR3001`	Route timed out error
`LTK_ROUTE_BAD_DESTINATION`	Routing destination is not near a routable road
`LTK_ROUTE_BAD_ORIGIN`	Origin is not near a routable road
`LTK_ROUTE_CANNOT_ROUTE`	No route can be found between the origin and the destination
`ROUTE_EMPTY_ROUTE`	Empty route code
`LTK_ROUTE_ERROR3006`	Network error
`LTK_ROUTE_ERROR3007`	Unknown error
`LTK_ROUTE_ERROR3008`	Route does not match
`LTK_ROUTE_ERROR3009`	Server error
`ROUTE_NO_DETOUR`	No route detour
`ROUTE_PED_ROUTE_TOO_LONG`	Route too long error
`ROUTE_NO_PEDESTRIAN_DETOUR`	No pedestrian route detour
`ROUTE_ORIGIN_NOT_IN` `_SUPPORTED_COUNTRIES`	Origin not in supported countries
`ROUTE_DESTINATION_NOT_IN` `_SUPPORTED_COUNTRIES`	Destination not in supported countries

NavKit_SampleApp Demonstration

Comtech provides an example application NavKit_SampleApp, that demonstrates various features of the Android NavKit SDK. The following sections describe how to build and run the NavKit_SampleApp.

Importing the Project

The following steps are performed to import the NavKit_SampleApp project.

Click Open existing Android Studio project from Studio Welcome Screen. If another project is already open in Studio, from the File menu, select Open.
Browse to the path androidSDK/sample/NavKit_SampleApp, select the option NavKit_SampleApp from the dropdown and click OK as shown in the following screenshot.

Figure 1. Importing the Project

Click OK in the Gradle Sync dialog to auto configure the Gradle wrapper for the project.

After Gradle sync is completed, NavKit_SampleApp and the libraries can be seen in the project explorer, as shown in the following screenshot.

Figure 2. NavKit_SampleApp in Project Explorer

Building and Running the NavKit_SampleApp

The following steps describe building and running the NavKit_SampleApp.

Before building the project, set the value for the API key.
Open the path com.locationtoolkit.navkit.sampleapp.common.Credential as shown in the following screenshot. Replace your_server_token with the API key assigned to you by Comtech.

Figure 3. Setting API Key

Run the NavKit_SampleApp to explore various navigation features. The following screenshot shows the main screen which has various route options.

Figure 4. NavKit_SampleApp Main Screen

Tapping Navigate on the main screen starts a Navigation session with all the selected options. The following screenshot shows a running navigation session.

Figure 5. Running Navigation Session

Note	To know more about all the interfaces and methods of Android NavKit, see the NavKit Android API Reference Document.

Android SDK