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