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

SDK Function Description
loadComputedRoute Loads an OFG route and starts navigation following that route
getRouteStatus Gets the status of OFG route in JSON format
startNavigation triggers the standard navigation to a starting point of an OFG route
stopNavigation triggers the standard navigation to a starting point of an OFG route

 

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

Field Type Default value Description
name string   caption on the point
version string n/a the file format version, supported: 1.0.0.2
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
color string #C0C0C080 the color string defined in the format RGBA format, example #FFA0522D. The color is applied on the point and the roadline starting from this point to the next one
instruction int -1 defines instruction to be given at the point, -1 denotes the instruction to be inferred automatically, -2 denotes no instruction is given, see the Instruction table bellow for details
roundaboutIndex int 1 the exit index defined for roundabout instructions
messageTts string   the text for the spoken instruction at the point

 

Instruction name int Index required
Remove Instruction -2 FALSE
Inferred Instruction -1 FALSE
Direction Keep Right 0 FALSE
Direction Keep Left 2 FALSE
Direction Easy Right 4 FALSE
Direction Easy Left 6 FALSE
Direction Right 8 FALSE
Direction Left 10 FALSE
Direction Sharp Right 12 FALSE
Direction Sharp Left 14 FALSE
Direction Straight 16 FALSE
Direction U Turn Right 17 FALSE
Direction U Turn Left 18 FALSE
Direction Roundabout SE 23 TRUE
Direction Roundabout E 24 TRUE
Direction Roundabout NE 25 TRUE
Direction Roundabout N 26 TRUE
Direction Roundabout NW 27 TRUE
Direction Roundabout W 28 TRUE
Direction Roundabout SW 29 TRUE
Direction Roundabout S 30 TRUE
Direction Roundabout SE_LS 32 TRUE
Direction Roundabout E_LS 33 TRUE
Direction Roundabout NE_LS 34 TRUE
Direction Roundabout N_LS 35 TRUE
Direction Roundabout NW_LS 36 TRUE
Direction Roundabout W_LS 37 TRUE
Direction Roundabout SW_LS 38 TRUE
Direction Roundabout S_LS 39 TRUE
Direction Ferry 40 FALSE
Direction State Boundary 41 FALSE
Direction Exit Right 43 FALSE
Direction Exit Left 44 FALSE

 
Version history

Version Release date Change log
1.0.0.2 1.3.2019 beta release for 3D
1.0.0.2 28.9.2015 1st official release for 2D
1.0.0.1 29.5.2015 beta release for 2D

 

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

Operation Description
1. Load and unload OFG route load OFG route and get into municipal navigation mode and back to standard navigation mode
2. Navigate to beginning of OFG route navigate to beginning of OFG route in order to get ready for OFG navigation mode
3. Pause OFG route Pause OFG route navigation in order to resume later
4. Resume OFG route Resume OFG navigation mode at the point it has been previosuly paused
5. Handle off-route scenario React on off-route events in an appropriate way
6. Join OFG route Join OFG route in order to handle road obstacles

1. Load and unload OFG route

In order to load OFG route, call ApiNavigation.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 ApiNavigation.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 ApiNavigation.startNavigation. If you want to see the OFG route during navigation to its start, you can simulatenously call ApiNavigation.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 ApiNavigation.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 = "/sdcard/routes/route_municipal_1.ofg";
    WayPoint ofgstart = FindOfgStart(routefile);  

    if (isCloseToCurrentPosition(ofgstart))
    {
        try {
            String jparams = "{\"startFromIndex\":0, \"showOnly\": false}";
            ApiNavigation.loadComputedRoute(routefile, jparams, 0);
        }
        catch (GeneralException ex)
        {
            Log.e("municipal", "LoadComputedRoute");
        }
    }
    else {

        try {
            String jparams = "{\"startFromIndex\":0, \"showOnly\": true}";
            ApiNavigation.loadComputedRoute(routefile, jparams, 0);
            ApiNavigation.startNavigation(ofgstart, 0, false, 0);
        } catch (GeneralException ex) {
            Log.e("municipal", "LoadComputedRoute");
        }
    }
}

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 ApiNavigation.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 ApiNavigation.stopNavigation.

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

    try {
        String routeStatus = ApiNavigation.getRouteStatus(0);
        JSONObject rs = new JSONObject(routeStatus);
        routeIndex = rs.getInt("currentIndex");
        JSONObject latlon = rs.getJSONObject("projectionToRoute");
        lat = latlon.getInt("lat");
        lon = latlon.getInt("lon");
        Log.i("municipal", "" + lat + "," + lon);
    }
    catch (JSONException ex)
    {
        Log.e("municipal", "JsonParsing");
    }
    catch (GeneralException ex)
    {
        Log.e("municipal", "GetRouteStatus");
    }

    try {
        ApiNavigation.stopNavigation(0);
    } 
    catch (GeneralException e) {
        Log.e("municipal", "StopNavigation");
    }
}

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.

    public static void Muni_Resume(int routeIndex, WayPoint ofgresume, boolean isCloseToCurrentPosition)
    {
        String routefile = "/sdcard/ofg/route_municipal_1.ofg";

        if (isCloseToCurrentPosition(ofgresume))
        {
            try {
                String jparams = "{\"startFromIndex\":" + routeIndex + ", \"showOnly\": false}";
                ApiNavigation.loadComputedRoute(routefile, jparams, 0);
            }
            catch (GeneralException ex)
            {
                Log.e("municipal", "LoadComputedRoute");
            }
        }
        else {

            try {
                String jparams = "{\"startFromIndex\":" + routeIndex + ", \"showOnly\": true}";
                ApiNavigation.loadComputedRoute(routefile, jparams, 0);
                ApiNavigation.startNavigation(ofgresume, 0, false, 0);
            } catch (GeneralException ex) {
                Log.e("municipal", "LoadComputedRoute");
            }
        }
    }

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).

public void onEvent(final int event, final String data) 
{
    if(event == ApiEvents.EVENT_OFF_ROUTE)
    {
    if(data != null)
    {
           if(data.compareTo("1") == 0)
               // driver got too far from OFG 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 = "/sdcard/ofg/route_municipal_1.ofg";

        try {
            String jparams = "{\"startFromIndex\":-1, \"showOnly\": false}";
            ApiNavigation.loadComputedRoute(routefile, jparams, 0);
        }
        catch (GeneralException ex)
        {
            Log.e("municipal", "LoadComputedRoute");
        }
    }