Navigation API

Overview

Navigation API is about getting into navigation mode after route calculation is done, and monitoring the navigation by means of events.
There are several functions, which start up the navigation mode, namely StartNavigation, NavigateToAddress, SetRoute and LoadComputedRoute. To prematurely abandon the navigation mode StopNavigation needs to be called.
During the navigation you can monitor the actual execution using GetRouteStatus, or control navigation using SkipNextWaypoint.
As navigation progresses various API events are generated and it is a decision of a programmer whether to react on the events, such as route finished, passing waypoint, speed limit exceeded, etc.

StartNavigation

StartNavigation triggers route calculation a navigation to a single destination point defined with GPS coordinates, specified by WayPoint class object.
The start position is selected to be an actual GPS position, or if not currently available, the last valid position is initially used. In case the valid position is not known the function gets into the "Waiting for valid position" state. Once the GPS fix is obtained the route calculation is automatically triggered and navigation mode entered.
There can be few exceptions occuring with the function call, the most typical one would be the "out of map" condition.
Check details of StartNavigation in the reference manual.

Example

This example shows how to start navigation from a given GPS coordinates and capture an error message in case of a problem.

  import com.sygic.sdk.remoteapi.ApiNavigation;
  import com.sygic.sdk.remoteapi.exception.NavigationException;
  import com.sygic.sdk.remoteapi.model.Position;
  import com.sygic.sdk.remoteapi.model.WayPoint;
  ...       
  void demo(double lat, double lon)
  {
    int x = (int)(lon * 100000);
    int y = (int)(lat * 100000);
    WayPoint wp = new WayPoint("B", x, y);  
    try {
        ApiNavigation.startNavigation(wp, 0, false, 0);
    } catch (NavigationException e) {       
       return ErrorMessage(e);
    }
    return "ok";
  }

  String ErrorMessage(NavigationException e)
  {
    String error = e.getMessage() + "/" + e.getCode();
    return error;
  }

Example

This example shows StartNavigation with fuzzy search on a given address string.

  import com.sygic.sdk.remoteapi.Api;
  import com.sygic.sdk.remoteapi.ApiLocation;
  import com.sygic.sdk.remoteapi.ApiNavigation;
  import com.sygic.sdk.remoteapi.exception.GeneralException;
  ...
  try {
     String address = "SVK,Bratislava,Einsteinova,18";
     boolean postal = false;
     boolean fuzzyMatch = true;
     Position pos = ApiLocation.locationFromAddress(address, postal, fuzzyMatch, 0);
     int flags = 0;
     boolean searchAddress = false;
     WayPoint wp = new WayPoint();
     wp.SetLocation(pos.getX(), pos.getY());
     ApiNavigation.startNavigation(wp, flags, searchAddress, 0);
  } 
  catch (GeneralException e) {
     Log.e("Navigation", "Error code:"+ e.getCode());
  }

NavigateToAddress

NavigateToAddress is similar to StartNavigation except that it takes the destination from an address string instead of explicit GPS latitude/longitude coordinates.
There can be few exceptions occuring with the function call, the most typical one would be an incorrect input of address string. The address string syntax is subject to address string specification, which follows the geocoding rules defined by LocationFromAddress.
Check details of NavigateToAddress in the reference manual.

Example

  import com.sygic.sdk.remoteapi.Api;
  import com.sygic.sdk.remoteapi.ApiLocation;
  import com.sygic.sdk.remoteapi.ApiNavigation;
  import com.sygic.sdk.remoteapi.exception.GeneralException;
  ...
  try {
     String address = "SVK,Bratislava,Einsteinova,18";
     boolean postal = false;
     int flags = 0;
     ApiNavigation.navigateToAddress(address, postal, flags, 0);
  } 
  catch (GeneralException e) {
     Log.e("Navigation", "Error code:"+ e.getCode());
  }

Example using postal scheme

  import com.sygic.sdk.remoteapi.Api;
  import com.sygic.sdk.remoteapi.ApiLocation;
  import com.sygic.sdk.remoteapi.ApiNavigation;
  import com.sygic.sdk.remoteapi.exception.GeneralException;
  ...
  try {
     String address = "SVK,811 09,Einsteinova,18";
     boolean postal = true;
     int flags = 0;
     ApiNavigation.navigateToAddress(address, postal, flags, 0);
  } 
  catch (GeneralException e) {
     Log.e("Navigation", "Error code:"+ e.getCode());
  }

SetRoute

SetRoute sets the given itinerary referenced by its name for route calculation followed by navigation.
The function is described in the Routing API section.

StopNavigation

StopNavigation cancel the routes and stops the navigation mode.
Cancel route is automatically done when navigation reaches the destination. This functions is applied with a premature stop.
Check details of StopNavigation in the reference manual.

Example

void cancel()
{
    try {
        ApiNavigation.stopNavigation(0);
    } catch (GeneralException e) {
        e.printStackTrace();
    }
}

GetRouteStatus

GetRouteStatus retrieves the status of route execution during navigation and mainly returns ETAs and remaining distances to routes' waypoints
being it a simple destination waypoint for single route or many with a complext itinerary.
The function is described in the Routing API section.

GetRoute

GetRoute retrieves the structure and geometry of a currently calculated route, expressing waypoints from the input itinerary and geometry points in between waypoints.
The function is described in the Routing API section.

SkipNextWaypoint

SkipNextWaypoint allows removing the approching waypoint from itinerary and thus cause route recalculation, as it is not anymore mandatory to pass the waypoint.
This function is typically called when a waypoint representing e.g. a customer delivery point is during navigation revoked.
Check details of SkipNextWaypoint in the reference manual.

Example

void skip()
{
    try {
        ApiItinerary.skipNextWaypoint(0);
    } catch (GeneralException e) {
        e.printStackTrace();
    }
}

Events

API Events allow monitoring of significant navigation events with a possibility to react on it.
There are various events available.

Event Associated data Description
EVENT_ROUTE_COMPUTED data content is json: { "itineraryId": "id" }. occurs when a route is initially computed and basically the navigation starts
EVENT_ROUTE_FINISH data content is json: { "itineraryId": "id" }. occurs when navigation reaches the destination within a defined hit radius
EVENT_WAIPOINT_VISITED id
id - identifies the waypoint (the itinerary's attribute waypointId)
(please bear with the waypoint typo) occurs when navigation passes a waypoint (except start and destination) within a defined hit radius
EVENT_ROUTE_USERCANCEL data content is json: { "itineraryId": "id" }. occurs when user cancels navigation on a calculated route prematurely either through GUI or API function
EVENT_OFF_ROUTE_EXT data content is json: { "itineraryId": "id" }. occurs when a driver leaves the prescribed route. This typically triggers the route recalculation. It extends the old event EVENT_OFF_ROUTE.
EVENT_SPEED_EXCEEDING occurs when a driver exceeds the speed limit on the current road
EVENT_POI_WARNING {poi_category}{poi_name}{lon,lat} occurs when in proximity of a warning-enabled POI within a defined hit radius
EVENT_RADAR_WARNING occurs when in proximity of a radar/speedcam POI within a defined hit radius in the same bearing direction
EVENT_RESTRICTED_ROAD occurs when a driver enters a restricted road
EVENT_GEOFENCE id,data
id - defines 0 when entering geofence, 1 when leaving
data - defines the string identifying the geofence (in Sygic3D the geofence's attribute notificationData)
occurs when a driver enters or leaves a defined geofence. Please note the notification must be enabled through the geofence's attribute notificationEnabled
EVENT_BORDER_CROSSING occurs when a driver crosses country border
EVENT_SPEED_LIMIT_CHANGED speedlimit
current speedlimit in units as would be returned by the function GetCurrentSpeedLimit
occurs when a driver passes the road point where speed limit is changed (the event available since the version 13.7.5)
EVENT_WAYPOINT_MARKED_AS_VISITED data content is json: { "waypointId": "id", "trigger": "manual|sdk" }. occurs when a waypoint is manually marked as visited or skipped through sdk call

Check for more on Api Events in the reference manual.

Example

import com.sygic.sdk.remoteapi.ApiCallback;
import com.sygic.sdk.remoteapi.events.ApiEvents;
import android.widget.Toast;
...
private Map<Integer,String> mEvents = new HashMap<Integer, String>();
private Api mApi;
private Handler mHandler = new Handler();
private ApiCallback mApiCallback = new ApiCallback() {

        @Override
        public void onServiceDisconnected() {
        }

        @Override
        public void onServiceConnected() {
            try {
                mApi.registerCallback();
            } catch (RemoteException e) {
                Log.e("RegisterCallback", "Error code:" + e.getMessage());
            }
        }

        @Override
        public void onEvent(final int event, final String data)
        {
            boolean show = false;
            switch (event) {
              case ApiEvents.EVENT_ROUTE_FINISH:
                  show = true;
                  break;
            }
            if (show)
            mHandler.post(new Runnable() {
               @Override
               public void run() {
                  String strToast = mEvents.get(event);
                  Toast.makeText(getApplicationContext(), strToast, Toast.LENGTH_SHORT).show();
               }
             });
        }
    };

@Override
protected void onCreate(Bundle savedInstanceState)
{
    ...
    mApi = Api.init(getApplicationContext(),  "com.sygic.fleet", Api.CLASS_FLEET, mApiCallback);
    mApi.connect();
    mEvents.put(ApiEvents.EVENT_ROUTE_FINISH, "Destination reached");
    ...
}

Exceptions

Problems with StartNavigation and NavigateToAddress functions are signaled with API Exceptions.
There are various exceptions possible.

Exception Description
NavigationException -4 occurs when the destination or a waypoint is not reachable due to map inconsistency, probably because of a missing map on a way
NavigationException -6 occurs when there is no valid GPS signal to incur starting point and there is no prior knowledge of a recent position
NavigationException -9 occurs when StartNavigation cannot map match the destination position. Possibly the destination is out of map.
...

Check for more on Api Exceptions in the reference manual.

Example

This example shows the capturing of the Waiting for valid signal exception.
However there is no need for special actions in this case. It is because the behavior of Navigation is defined so that it internally waits for a valid GPS signal and once it is fixed the navigation automatically calculates a route and starts navigation.

void demo(double lat, lon)
{
    try {
       int x = (int)(lon * 100000);
       int y = (int)(lat * 100000);
       WayPoint wp = new WayPoint("xy", x, y);
       ApiNavigation.startNavigation(wp, 0, false, 0);
       Log.d("Info", "navigation started immediately");
    }
    catch (NavigationException e)
    {
       if (e.getCode() == -6)
       {
          Log.d("Info", "navigation is deferred till GPS fix");
       }
    }
}