Routing API

Overview

Routing API is about to work with routes and itineraries using json file format.
There are functions, which allow sending json route or itinerary for route calculation and subsequent navigation,
and functions, which allow retrieving actual route real-time status either at a detail of waypoints or even geometry.

You can create a new itinerary through AddItinerary or delete an existing one through DeleteItinerary.
Itineraries are defined with a list of waypoints, each represented primarily with gps coordinates and optionally with a time window, which defines a desired visiting time. And then you can send itinerary to navigation through SetRoute and in real time to monitor the itinerary execution through GetRouteStatus. The exact route geometry calculated by routing engine can be retrieved through GetRoute.

You can also load a route generated in an external system through LoadComputedRoute and put it to navigation. There are few json as well as other formats specified for the import. External routes are defined with a list of waypoints along with an exact geometry to be followed in between waypoints. Such route can be monitored during navigation at a waypoint level through GetRouteStatus as well as with a full geometry by GetRoute.

The itinerary and route functions operate with several json objects, namely:

Json itinerary object is used with AddItinerary, SetRoute
Json itinerary status object is used with GetRouteStatus
Json route import object is used with LoadComputedRoute
Json route export object is used with GetRoute

Itinerary object (.sif)

The json specification of the supported structure is shown in the diagram bellow.
The fields denoted with * are mandatory.

Table of json fields

Field	Type	Default value	Description
id	string		itinerary identifier
name	string		name of the itinerary
description	string		short description
version	string		file format version, supported are: 2.1, 2.2
allowItineraryEdit	bool	true	allows or disallows manual edit of itinerary once loaded into navigation
routeComputeType	string: car\|truck\|bus\|camper\|van\|pedestrian	car	defines the vehicle routing preference applied between waypoints or for the whole itinerary
routeComputeMethod	string: fastest\|shortes\|economical	fastest	defines the routing method preference applied between waypoints
avoidTollRoads	bool	false	defines the routing attribute for toll roads
avoidSpecialArea	bool	false	defines the routing attribute for special city zones
avoidMotorways	bool	false	defines the routing attribute for motorways/highways
avoidUnpavedRoads	bool	false	defines the routing attribute for unpaved roads
ignoreProhibited	bool	false	defines the routing attribute for ignoring prohibited maneuvers
ignoreOneWays	bool	false	defines the routing attribute for ignoring oneway driving rule
lat	int	0	latitude position defined as WGS84 multiplied by 100,000
lon	int	0	longitude position defined as WGS84 multiplied by 100,000
lonNavi	int	=lon	navigable longitude position defined as WGS84 multiplied by 100,000
latNavi	int	=lat	navigable latitude position defined as WGS84 multiplied by 100,000
hitRadius	int	50	distance in meters from the waypoint considered as visiting criteria
hitSpeed	int	50	reference speed at which hitRadius holds exactly, for higher speeds the hitRadius is linearly increased
type	string: start\|via\|finish	via	the type of waypoint
waypointId	int	-1	user defined identification of the waypoint
caption	string		waypoint name shown in the route summary, by default the name is indicated by its exact address
startTime	string		defines the starting time of a time window in the UTC format, example 2015-03-06T14:15:00Z
endTime	string		defines the ending time of a time window in the UTC format, example 2015-03-06T14:30Z
stopDelay	int	0	defines the service time in seconds expected to spent on the waypoint
icon	string: wp_fuel \| wp_load \| wp_unload \| wp_pause		defines the icon display of the waypoint on map. The name referes to the png picture contained in the folder /Res/icons/waypoints, and is limited to the one of the four enumerated names. Example icon="wp_fuel" refers to "wp_fuel.png" or "wp_fuel_visited.png", thus requires both pictures to be available in the folder.

Example of the itinerary with 3 waypoints:

{
"name":     "Itinerary-627",
"version":  "2.2",
"routeParts":
   [{
        "directives":
        {
            "routeComputeType": "car",
            "routeComputeMethod":   "fastest",
            "avoidTollRoads":       true,
            "avoidSpecialArea": false,
            "avoidMotorways":   false,
            "avoidFerries":             false,
            "avoidUnpavedRoads":    true,
            "ignoreProhibited": false,
            "ignoreOneWays":        false
        },
        "waypointFrom":
        {
            "timeWindow":
            {
                "startTime": "2015-06-16T14:00:00Z",
                "endTime": "2015-06-16T14:30:30Z",
                "stopDelay": 120
             },
            "lon":              1711001,
            "lat":              4814955,
            "type":          "via",
            "waypointId":   1,
            "hitRadius":    100
        },
        "waypointTo":
        {
            "lon":           1710758,
            "lat":           4814795,
            "type":          "via",
            "waypointId":   2,
            "hitRadius":    100
        }
   },{
        "directives":
        {
            "routeComputeType": "car",
            "routeComputeMethod":   "shortest"
        },
        "waypointTo":
        {
            "timeWindow":
            {
                "startTime": "2015-06-16T15:00:00Z",
                "endTime": "2015-06-16T15:30:30Z",
                "stopDelay": 120
            },
            "lon":              1710375,
            "lat":              4814391,
            "type":             "finish",
            "waypointId":   3,
            "hitRadius":    100
        }
    }]
}

Itinerary status object

The specification of the supported json fields is shown in the diagram bellow. Some fields denoted by * can be omitted, which is in case the value is not valid. E.g. the field timeArrival when the waypoint is not yet visited.

Table of json fields

Field	Type	Default value	Description
itineraryId	string		itinerary identifier
timeStamp	string	-	the timestamp of the current status
numVisited	int	-	number of waypoints already visited. The start waypoint is counted too.
numUnvisited	int	-	number of waypoints not yet visited
numPredictedLateArrivals	int	-	number of waypoints predicted to have late arrivals
numPredictedEarlyArrivals	int	-	number of waypoints predicted to have early arrivals
timeRemaining	int	-	time in seconds estimated to reach the finish
distanceRemaining	int	-	distance in meters estimated to reach the finish
distancePassed	int	-	distance in meters passed from start
lat	int	-	latitude position defined as WGS84 multiplied by 100,000
lon	int	-	longitude position defined as WGS84 multiplied by 100,000
lonNavi	int	-	navigable longitude position defined as WGS84 multiplied by 100,000
latNavi	int	-	navigable latitude position defined as WGS84 multiplied by 100,000
hitRadius	int	-	distance in meters from the waypoint considered as visiting criteria
type	string: start\|via\|invisible\|finish	-	the type of waypoint
status	string: visited\|unvisited\|none	-	the status of the waypoint
edited	bool	-	indicates whether the waypoint was manually edited since itinerary loading into navigation
timeArrival	string	-	defines the actual arrival time at the waypoint in the UTC format if already visited, example 2015-03-06T14:15:00Z
estimatedTimeArrival	string	-	defines the estimated arrival time at the waypoint in the UTC format if not yet visited, example 2015-03-06T14:30Z
realtimeStatus: timeRemaining	int	-	time in seconds estimated to reach the waypoint
realtimeStatus: distanceRemaining	int	-	distance in meters estimated to reach the waypoint

Example of the itinerary status with 3 waypoints:

{
    "timeStamp": "2015-06-28T16:10:37Z",
    "numVisited": 1,
    "numUnvisited": 2,
    "numPredictedLateArrivals": 0,
    "numPredictedEarlyArrivals": 1,
    "timeRemaining": 1312,
    "distancePassed": 0,
    "distanceRemaining": 8610,
    "waypoints":
    [{
            "lon":  1711468,
            "lat":  4813110,
            "type": "start",
            "waypointId":   1,
            "hitRadius":    200,
            "timeWindow":
            {
                "startTime":  "2015-06-28T16:00Z",
                "endTime":  "2015-06-28T16:30Z",
                "stopDelay":  180
            },
            "realtimeStatus":
            {
                "status":  "visited",
                "edited":  false
            }
    }, {
            "lon":  1713067,
            "lat":  4816062,
            "type":  "via",
            "waypointId":  2,
            "hitRadius":  200,
            "timeWindow":
            {
                "startTime":  "2015-06-28T16:15Z",
                "endTime":  "2015-06-28T16:30Z",
                "stopDelay":  180
            },
            "realtimeStatus":
            {
                "status":  "unvisited",
                "estimatedTimeArrival": "2015-06-28T16:19:25Z",
                "timeRemaining":  528,
                "distanceRemaining":  5018,
                "edited":  false
            }
    }, {
            "lon":  1710000,
            "lat":  4814722,
            "type": "finish",
            "waypointId":   3,
            "hitRadius":    200,
            "timeWindow":
            {
                "startTime":  "2015-06-28T17:00Z",
                "endTime":  "2015-06-28T17:30Z",
                "stopDelay":  180
            },
            "realtimeStatus":
            {
                "status":  "unvisited",
                "estimatedTimeArrival":  "2015-06-28T16:29:29Z",
                "timeRemaining":  1132,
                "distanceRemaining":  8610,
                "edited":  false
            }
        }]
}

Route object

This json object is used with LoadComputedRoute for importing routes generated in external systems, e.g. the export of a Route Optimization software.
Currently we support two formats: Sygic-native format (sif files) and PTV-compatible format.
Sygic SDK function automatically recognizes the used format.

Disclaimer: Since app version 21.1.0 a new map matching algorithm is used for .json (PTV) file format.
In order use the legacy magnetic routing algorithm, simply rename the .json file extension to .omc (original magnetic compute) and load the .omc file instead.

1. PTV-compatible format (.json, .bcr)

These files can be obtained through exports from PTV route calculation services, like xServer, etc.
The json specification of the supported structure:

Table of json fields

Field	Type	Default value	Description
x	double	n/a	longitude position defined as WGS84 multiplied by 100,000
y	double	n/a	latitude position defined as WGS84 multiplied by 100,000
polyIdx	int	n/a	index reference to the points array defining the GPS point as the waypoint/station
WayPointType	string	n/a	the type of waypoint, possible values are START, VIA, DEST.

Example

{
  "polygon": {
    "lineString": {
      "points": [
        {
          "x": 1712571,
          "y": 4814643
        },
        {
          "x": 1712486,
          "y": 4814651.5
        },
        {
          "x": 1712461,
          "y": 4814652
        },

...
        {
          "x": 1712302,
          "y": 4814263
        },
        {
          "x": 1712355,
          "y": 4814257
        },
        {
          "x": 1712468,
          "y": 4814248
        }
      ]
    }
  },
  "stations": [
    {
      "polyIdx": 0,
      "wayPointType": "START"
    },
    {
      "polyIdx": 44,
      "wayPointType": "VIA"
    },
    {
      "polyIdx": 83,
      "wayPointType": "DEST"
    }
  ]
}

2. Sygic-native format (.sif)

The json specification of the supported structure (version 1.1) :

Table of json fields

Field	Type	Default value	Description
name	string	""	route name appearing in route info dialog
description	string	""	route description appearing in route info dialog
version	string	n/a	used version, currently available 1.0 and 1.1
lat	int	n/a	latitude position defined as WGS84 multiplied by 100,000
lon	int	n/a	longitude position defined as WGS84 multiplied by 100,000
type	string	n/a	the type of the waypoint, possible values are start, via, finish.
waypointId	int	-1	user defined identification of the waypoint
id	int	-1	user defined identification of the road

Example

{
"name":     "Route-77",
"version":  "1.1",
"routeParts":
   [{
        "waypointFrom":
        {
            "lat":          4814951,        
            "lon":          1711001,
            "type":         "start"
        },
        "waypointTo":
        {
            "lat":           4814791,       
            "lon":           1710751,
            "type":          "via"
        }
        "roads":
        [
          {  
             "id": 1, 
             "points": [ { lat: 4814952, lon: 1711002 }, { lat: 4814953, lon: 1711003 }, { lat: 4814954, lon: 1711004 } ]
          },
          {  "id": 2,
             "points": [ { lat: 4814955, lon: 1711005 }, { lat: 4814956, lon: 1711006 }, { lat: 4814957, lon: 1711007 } ]
          }
          ...
        ]
   },{
        "waypointTo":
        {
            "lat":          4814391,
            "lon":          1710371,            
            "type":         "finish"
        }
        "roads":
        [
          {  
             "id": 25, 
             "points": [ { lat: 4814791, lon: 1710751 }, { lat: 4814792, lon: 1710752 }, { lat: 4814793, lon: 1710753 }, ... ]
          },
          ...
        ]       
   }]
}

AddItinerary

AddItinerary adds itinerary to the system database for immediate or later usage. It takes as an input json string, which defines the itinerary. The itinerary is basically a list of waypoints, each denoted as START, VIA or FINISH. Formally the itinerary is comprised of list of routeparts, while each routepart defines start and end waypoint.
Another input to the function is the name of the itinerary, which serves as a reference for function to put it into route calculation and navigation, which is SetRoute.
Check details of AddItinerary in the reference manual.
Please note AddItinerary with json support is only available with the 3D version of navigation.

Example

This example demonstrates how to create a new itinerary in a json format.
We create an itinerary with 3 waypoints, each defined with GPS coordinates, time windows and type of the waypoint.
The 3 waypoints are delivered in a ArrayList.
The result of the demo function is placing an itinerary into application ready to be used for navigation.
In the example we use the json library "json.org", which offers convenient manipulations with json strings and objects for construction and parsing.
For the definition of Sygic Json strings please refer to the section Json Itinerary Object above.

void demo()
{       
    var lst = new List<TwWaypoint>();
    lst.add(new TwWaypoint(48.11468, 17.13110, "2017-06-28T16:00:00Z", "2017-06-28T16:00:00Z", "start"));
    lst.add(new TwWaypoint(48.13067, 17.16062, "2017-06-28T17:00:00Z", "2017-06-28T17:30:00Z", "via"));
    lst.add(new TwWaypoint(48.10039, 17.14722, "2017-06-28T18:00:00Z", "2017-06-28T18:30:00Z", "finish"));

    string json = CreateJsonItinerary(lst);
    string filename = "Itinerary-453";
    SError err;
    int ret = CApplicationAPI.AddItinerary(out err, json, filename, 0);
    if (ret == 1)
        Debug.WriteLine("Itinerary created successfully.");
    else
    {
        Debug.WriteLine("Itinerary create error.");
        return;
    }
}

// Json construction and parsing helpers

public class TwWaypoint 
{
    double lat;
    double lon;
    string dtStart;
    string dtEnd;
    string wpType;
    public TwWaypoint (double lat, double lon, string dtStart, string dtEnd, String wpType)
    {
        this.lat = lat;
        this.lon = lon;
        this.dtStart = dtStart;
        this.dtEnd = dtEnd;
        this.wpType = wpType;
    }
}   

protected string CreateJsonItinerary(List<TwWaypoint> lst)
{
   //tbd
}

DeleteItinerary

DeleteItinerary deletes the given itinerary from the system database referenced by its name.
Check details of DeleteItinerary in the reference manual.

void demo()
{       
    SError err;

    int ret = CApplicationAPI.DeleteItinerary(out err, filename, 0);
    if (ret == 1)
        Debug.WriteLine("Itinerary deleted successfully.");
    else
        Debug.WriteLine("Itinerary delete error.");
}

SetRoute

SetRoute sets the given itinerary referenced by its name for route calculation. And if successful, the navigation mode is immediately switched on and a driver is navigated over the waypoints.
Check details of SetRoute in the reference manual.

Example

The example creates an itinerary with 3 waypoints (using self-made function CreateItinerary) and passes it to the navigation.

void demo()
{
    string filename = "Itinerary-362";

    PointF P1 = new PointF(48.1891, 17.1817, "start");
    PointF P2 = new PointF(48.1739, 17.1431, "via");
    PointF P3 = new PointF(48.1416, 17.1248, "finish");
    string json = CreateItinerary(P1, P2, P3);

    SError err;

    int ret = CApplicationAPI.AddItinerary(out err, json, filename, 0);
    if (ret == 1)
        Debug.WriteLine("Itinerary created successfully.");
    else
    {
        Debug.WriteLine("Itinerary create error.");
        return;
    }

    int flags = 0;
    bool bShowNavigation = true;
    ret = CApplicationAPI.SetRoute(out err, filename, flags, bShowNavigation, 0);
    if (ret == 1)
        Debug.WriteLine("Routing finished successfully.");
    else
        Console.WriteLine("Error {0}:{1}", err.GetCode(), err.GetDescription());        
}

Example

This example shows the error generated due to passing an invalid waypoint into the itinerary.
Invalid means either a non-existent GPS position or though existing but not reachable within the currently loaded map.
The error message also identifies the first problematic waypoint by index, which is defined in the ascending order starting from 0, while the start waypoint has the index -1.
The below example should produce the message Error -9:waypoint [0] from itinerary was not found

    string filename = "Itinerary-363";

    PointF P1 = new PointF(48.1891, 17.1817, "start");
    PointF P2 = new PointF(47.1725, -35.5307, "via");  // middle of the ocean
    PointF P3 = new PointF(48.1416, 17.1248, "finish");
    string json = CreateItinerary(P1, P2, P3);

    SError err;

    int ret = CApplicationAPI.AddItinerary(out err, json, filename, 0);
    if (ret == 1)
        Debug.WriteLine("Itinerary created successfully.");
    else
    {
        Debug.WriteLine("Itinerary create error.");
        return;
    }

    int flags = 0;
    bool bShowNavigation = true;
    ret = CApplicationAPI.SetRoute(out err, filename, flags, bShowNavigation, 0);
    if (ret == 1)
        Debug.WriteLine("Routing finished successfully.");
    else
        Console.WriteLine("Error {0}:{1}", err.GetCode(), err.GetDescription());  
}

GetRouteStatus

Example

This example demonstrates how to retrieve current status of the itinerary execution, here placed into a user-defined formatted string.
When retrieving the execution status we can read out e.g. the information about the number of visited and unvisited waypoints, and then per each waypoint more detailed info such as ETA, remaining distance and time to the waypoint, etc.
In the example we used the json library json.org, which offers convenient manipulations with json strings and objects for construction and parsing.
Check details of GetRouteStatus in the reference manual.
Please note GetRouteStatus is only available with the 3D version of navigation.

void demo()
{
    SError err; 
    string status
    int ret = CApplicationAPI.GetRouteStatus(out error, out status, 1000);  
    if (ret == 1)
    {
    ParseRouteStatus(status);
    }
}

void ParseRouteStatus(string status)
{
    //tbd
}

LoadComputedRoute

LoadComputedRoute imports a given route referenced by its filename into navigation engine. And if successful, the navigation mode is immediately switched on and a driver is navigated over the waypoints and following the route geometry in a magnetic way.
In case a deviation from route occurs the recalculation is triggered, which tries to navigate driver back to the original route in a most efficient way.
Check details of LoadComputedRoute in the reference manual.

Example

void demo()
{
    SError err; 
    string filename = "c:/SygicData/myroutes/route_66.json";
    int ret = CApplicationAPI.LoadComputedRoute(out error, filename, 0);
    if (ret != 1)
    {
       CApplicationAPI.FlashMessage(out error, error.GetDescription(), true, 0);
    }
}

GetRoute

GetRoute retrieves currently calculated route, containing waypoints and geometry, in a json string.
The json format can be of two types (Sygic and PTV). Please check the section Json Route Object.
If there is no route calculated the functions returns error.
Check details of GetRoute in the reference manual.

Example

void demo()
{
    SError error;
    string geometry;
    int format = 0;  // 0-Sygic, 1-PTV
    int ret = CApplicationAPI.GetRoute(out error, format, 1, out geometry, 0);
    if (ret != 1)
    {
    CApplicationAPI.FlashMessage(out error, error.GetDescription(), true, 0);
    }
}

Previous article: Navigation API
Next article: Maps API