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 current GPS coordinates and capture an error message in case of a problem.

  using ApplicationAPI;

  void demo()
  {
        SError err;
        int ret;
        int maxTime = 0;

        SGpsPosition gps = new SGpsPosition();
        bool bSatellitesInfo = false;
        maxTime = 0;
        ret = CApplicationAPI.GetActualGpsPosition(out err, out gps, bSatellitesInfo, maxTime);
        if (ret != 1)
        {
           return; // problem
        }
        lat = gps.Latitude;
        lon = gps.Longitude;

        int flags = 0;
        bool bShowNavigation = true;
        bool bSearchAddress = false;
        maxTime = 0;
        SWayPoint wp = new SWayPoint();
    int x = (int)(lon * 100000);
    int y = (int)(lat * 100000);
        wp.Location.lX = x;
        wp.Location.lY = y; 
    WayPoint wp = new WayPoint("B", x, y);  
        if (CApplicationAPI.StartNavigation(out err, ref wp, flags, bShowNavigation, bSearchAddress, maxTime) != 1)
        {
           // problem
        }
}

Example

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

using ApplicationAPI;

void demo()
{
    string strAddress = "SVK,Bratislava,Einsteinova,18";    
    SError err;
    int maxTime = 0; 

    bool postal = false;
    bool fuzzy = true;
    LONGPOSITION location;
    int ret = CApplicationAPI.LocationFromAddress(out err, out location, strAddress, postal, fuzzy, maxTime);
    if (ret != 1)
    {
       return;
    }

    int flags = 0;
    bool bShowNavigation = true;
    bool bSearchAddress = true;
    SWayPoint wp = new SWayPoint();    
    wp.Location.lX = location.lX;
    wp.Location.lY = location.lY;
    if (CApplicationAPI.StartNavigation(out err, ref wp, flags, bShowNavigation, bSearchAddress, maxTime) != 1)
    {
       // problem
    }
}

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

using ApplicationAPI;

void demo()
    string address = "SVK,Bratislava,Einsteinova,18";
    SError err;
    boolean postal = false;
    boolean bShowNavigation = true;
    int flags = 0;
    int ret = CApplicationAPI.NavigateToAddress(out err, address, postal, flags, bShowNavigation, 0);
    if (ret != 1)
    {
       // problem
    }

Example using postal scheme

using ApplicationAPI;

void demo()
    string address = "SVK,811 09,Einsteinova,18";
    SError err;
    boolean postal = true;
    boolean bShowNavigation = true;
    int flags = 0;
    int ret = CApplicationAPI.NavigateToAddress(out err, address, postal, flags, bShowNavigation, 0);
    if (ret != 1)
    {
       // problem
    }

SetRoute

SetRoute sets the given itinerary referenced by its name for route calculation followed by navigation.
The function is described in the Routes 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

using ApplicationAPI;

void cancel()
{
    SError err;
    int ret = CApplicationAPI.StopNavigation(out err, 0);
    if (ret != 1)
    {
       // problem
    }
}

GetRouteStatus

GetRouteStatus retrieves the status of route execution during navigation and mainly returns ETAs and remaining distances to routes' waypoints
being it a simple destinaation waypoint for single route or many with a complext itinerary.
The function is described in the Routes 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()
{
    SError err;
    int ret = CApplicationAPI.SkipNextWaypoint(out err, 0);
    if (ret != 1)
    {
       // problem
    }
}

Events

API Events allow monitoring of significat 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 details of Api Events in the reference manual.

Example

void NaviHandler(int nEventID, IntPtr strData)
{
    // cast the event to ApplicationEvents enumeration
    ApplicationEvents anAppEvent = (ApplicationEvents)nEventID;

    // handle event
    switch (anAppEvent)
    {
      case ApplicationEvents.EVENT_ROUTE_FINISH:
         Debug.WriteLine("Destination reached.");
         break;
    }
}

int StartSygic()
{
    string mySygicPath = ...
    IntPtr inParentWnd = ...
    CApplicationAPI.ApplicationHandler AppHnd = new CApplicationAPI.ApplicationHandler(NaviHandler);
    int ret = CApplicationAPI.InitApi(mySygicPath, AppHnd, 0, 0, 320, 240, true, false, inParentWnd);
    return ret;
}