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.

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.

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");
       }
    }
}