Municipal API

Introduction

Municipal navigation is the feature that allows drivers to be navigated in the mode suitable for execution of municipal services. That is, when one needs a navigation in complicated trajectories not always matching the official road network. An example is the waste management service where the vehicle sometimes needs to go off-road or into a forbidden zone and where driver needs to be given custom instructions such as "collect the bin on the right side".
The Municipal feature is supported by use of municipal API functions and OFG json route object, and it is reflected by a special navigation mode called municipal navigation mode, which is triggered by use of LoadComputedRoute API function.

Requirements and limitations

The feature is supported since the release 13.9.1 and is under extra licensing

• the navigation license (mlm / content.info file) must contain the guided route permission: municipalServices=yes

Integration

Municipal feature is supported with the following API functions.
Note that API functions operate with routes using a proprietary Sygic municipal route format called OFG (municipal offroad guide route format). Therefore we refer to municipal routes as OFG routes.

API functions

Usecase example

OFG routes can be imported to navigation from any web based solution, which allows construction and editing of routes. Such tool can apply a simple json conversion and import a route through the Sygic API call LoadComputedRoute.
An example of a Municipal route generator shown bellow can be quickly designed e.g. by use of Google map services.

Json Municipal Route object

This route object is used with the overloaded SDK function LoadComputedRoute, through which one can send a guided route to the navigation while the navigation switches to the special navigation mode, in which it tries to navigate drivers using the defined geometry, i.e. even on the roads or trajectories not covered by current maps.
Such routes can be extended with additional information such as coloring for visualization and possible TTS messaging.
 

Route format

The json specification of the supported structure is shown in the diagram bellow. The filenames of this type of route have the suffix ofg.
The fields denoted with * are mandatory.

Table of json fields

 
Version history

Json example

An example of the route for waste management trip:

{
  "name":"Bratislava wastecollection route#1",
  "version":"1.0.0.2",
  "guidePoints": 
  [
    {
      "lon": 1712838,
      "lat": 4816011
    },
    {
      "lon": 1712916,
      "lat": 4816097,
      "color": "#FFA0522D",
      "name": "New point",
      "instruction": 26,
      "roundaboutIndex": 3,
      "messageTts": "Collect left"
    },
    {
      "lon": 1712804,
      "lat": 4816143,
      "color": "#FFB8860B",
      "name": "New point",
      "instruction": 2,
      "messageTts": "Collect both sides"
    },
    {
      "lon": 1712750,
      "lat": 4816117
    },
    {
      "lon": 1712630,
      "lat": 4816157,
      "color": "#FFFFD700",
      "name": "New point"
    },
    {
      "lon": 1712650,
      "lat": 4816260,
      "color": "#FFCD5C5C"
    },
    {
      "lon": 1712968,
      "lat": 4816158
    },
    {
      "lon": 1712998,
      "lat": 4816195
    },
    {
      "lon": 1712816,
      "lat": 4816258
    },
    {
      "lon": 1712712,
      "lat": 4816294
    },
    {
      "lon": 1712727,
      "lat": 4816356
    }
  ]
}

Getting started

In the following we will demonstrate programming of few usecases using API functions for municipal support, which might be helpful for a solution provider.

Usecases

1. Load and unload OFG route

In order to load OFG route, call LoadComputedRoute with the route filename having the suffix ofg. Navigation will switch to the OFG navigation mode. In this mode vehicle is not snapped to a road network but rather blue thin line appears, showing the point on the OFG route closest from your vehicle. If you want to unload OFG route, call StopNavigation. Navigation is then switched back to the standard navigation mode (vehicle snapped to a road network).

2. Navigate to beginning of OFG route

Before loading OFG route, you can consider that driver should be navigated to the beginning of the OFG route using standard navigation mode. First, you will have to retrieve the start point of the OFG route , so that you can get navigated to this point. To get the location, you have to parse the OFG file by yourself. Then you can call StartNavigation. If you want to see the OFG route during navigation to its start, you can simulatenously call LoadComputedRoute with the flag showOnly:true contained in the params string. This will ensure that an OFG route will be visible, but you will stay in standard navigation mode. When arriving to the start point, you will receive EVENT_ROUTE_FINISH. To switch to the OFG navigation just call LoadComputedoute with the flag showOnly:false.
Note: You may consider whether to use or not the navigation to the start point of the OFG route. For example if the vehicle is close to the start of an OFG route, you may want to skip navigating to the start point.

void start()
{
    string routefile = DATAPATH + "route_municipal_1.ofg";

    SWayPoint ofgstart = FindOfgStart(routefile);
    SError error;

    if (isCloseToCurrentPosition(ofgstart))
    {
    string jparams = "{\"startFromIndex\": 0, \"showOnly\":false}";
    CApplicationAPI.LoadComputedRoute(out error, routefile, jparams, 0);
    }
    else
    {
    string jparams = "{\"startFromIndex\": 0, \"showOnly\":true}";
    CApplicationAPI.LoadComputedRoute(out error, routefile, jparams, 0);
    CApplicationAPI.StartNavigation(out error, ref ofgstart, 0, true, false, 0);
    }

}

3. Pause OFG route

For some cases you may want to pause the current OFG navigation, get navigated from it in a standard navigation mode and return to the pause point later to continue. First you have to get the current status of the OFG navigation through GetRouteStatus. From the resulting JSON string you can parse out the current index of OFG route (represents state and the progress of the OFG route execution) and GPS coordinates of vehicle's current position on OFG route. Store these values for the purpose of resuming the route and call StopNavigation.

void pause()
{
    int routeIndex = -1;
    int lat;
    int lon;

    SError error;
    String routeStatus;
    CApplicationAPI.GetRouteStatus(out error, out routeStatus, 0);
    routeIndex = GetJsonVal(routeStatus, "currentIndex");
    lat = GetJsonVal(routeStatus, "projectionToRoute.lat");
    lon = GetJsonVal(routeStatus, "projectionToRoute.lon");
    Console.WriteLine("municipal", "" + routeIndex + ":" + lat + "," + lon);

    CApplicationAPI.StopNavigation(out error, 0);
}

4. Resume OFG route

If you want to return back to the previously paused point, use the same routine as for navigation to start point, but use the values retrieved and stored when pausing.

void resume(int routeIndex, SWayPoint ofgresume )
{
    string routefile = DATAPATH + "route_municipal_1.ofg";

    SError error;
    if (isCloseToCurrentPosition(ofgresume))
    {
    string jparams = "{\"startFromIndex\": "+ routeIndex + ", \"showOnly\":false}";
    CApplicationAPI.LoadComputedRoute(out error, routefile, jparams, 0);
    }
    else
    {
    string jparams = "{\"startFromIndex\": "+ routeIndex + ", \"showOnly\":true}";
    CApplicationAPI.LoadComputedRoute(out error, routefile, jparams, 0);
    CApplicationAPI.StartNavigation(out error, ref ofgresume, 0, true, false, 0);
    }
}

5. Handle off-route situation

If the driver gets too far from an OFG route, EVENT_OFF_ROUTE is triggered. The event data is equal to "1". If the driver comes back in a near proximity to the route, the same event is triggered but with the data equal to "0".
Note that driver will be guided to the point where he left the route. If this point is not reachable, he should be given the possibility to "join" the route (see this usecase in a next section).

void NavHandler(int nEventID, IntPtr strData) 
{
    if (nEventID == (int)ApplicationEvents.EVENT_OFF_ROUTE)
    {
       int val = Convert2Int(strData);
       if (val == 1)
       {
       // driver got too far from route
       }
       else
       {
       // driver is back on OFG route
       }
    }
}

6. Join OFG route

If the user is off route and he cannot reach his abandoned position on the OFG route, he should be able to continue following the route from his current position. In this case call LoadComputedRoute with the startIndex -1. This will reset driver's current position on the OFG route to the closest point on route to vehicle.

void join()
{
    string routefile = DATAPATH + "route_municipal_1.ofg";

    SError error;
    string jparams = "{\"startFromIndex\": -1, \"showOnly\":false}";
    CApplicationAPI.LoadComputedRoute(out error, routefile, jparams, 0);
}