Maps API

Overview

Maps API provides functions for visualization of a custom layer of geometrical objects on map. The objects for visualization can be of the types point, polyline and polygon. The polygon object adds on the extra support for possible geofence notification.
The functions LoadExternalFile and UnloadExternalFile serve for visualization of polylines and polygons, and geofence support.
In Sygic 3D version we introduce the new function LoadGeoFile and UnloadGeoFile, which can manage more objects such as point, line, polyline, polygon as well as geofencing under the roof of enhanced GeoJSON specification.
There are also functions, through which you can control the map view such as ShowRectangleOnMap and ShowCoordinatesOnMap to display a specific location with a defined zoom.
The function SwitchMap allows management of different map configurations.

LoadGeoFile / UnloadGeoFile

LoadGeoFile allows loading of the GeoJSON formatted file containing map geometry objects for visualization on map and notification where available. UnloadGeoFile removes the objects from map, UnloadGeoFiles removes all loaded objects at once.
Check details of LoadGeoFile, UnloadGeoFile and UnloadGeoFiles in the reference manual.
This function works with the GeoJSON format, which extends on the specification of GeoJSON.
The function is not supported in Sygic2D (please check LoadExternalFile).

Note, it is the responsibility of a programmer to unload all loaded map objects by the exit of the application. In case this does not happen the object will stay present in the file system (Res/geofiles) and becomes kind of permanent, i.e. it gets automatically loaded with the start of the application no matter LoadGeoFile has been called or not.

Note, the geofiles can also be used outside of the API function by importing a file into Res/geofiles.
For more details check the FAQ How to import geofiles into navigation.

Please note this function feature is subject to extra licensing set as geoFiles=yes in a license file.

Example

This example loads visualization layer on map comprised of geometry objects defined the file EmergencyLayer.json.
And then (typically by end of the application) it is unloaded.

    String json = ReadFile("/sdcard/MyGeo/EmergencyLayer.json");
    try {
        ApiMaps.loadGeoFile("geo1", json, 0);
    } catch (GeneralException e) {
       Log.d("Error", "load geo file error");
    }

    ...

    try {
        ApiMaps.unloadGeoFile("geo1", 0);
    } catch (GeneralException e) {
       Log.d("Error", "unload geo file error");
    }       

Example

This example loads multiple layers on map and then (typically by end of the application) unloads them all.

    String json1 = ReadFile("/sdcard/MyGeo/EmergencyLayer.json");
    String json2 = ReadFile("/sdcard/MyGeo/DangerZones.json");
    try {
        ApiMaps.loadGeoFile("geo1", json1, 0);
        ApiMaps.loadGeoFile("geo2", json2, 0);
    } catch (GeneralException e) {
       Log.d("Error", "load geo file error");
    }

    ...

    try {
        ApiMaps.unloadGeoFiles(0);
    } catch (GeneralException e) {
       Log.d("Error", "unload geo file error");
    }       

LoadExternalFile / UnloadExternalFile

LoadExternalFile allows loading of the old format of polylines or geofences and its visualization on map. UnloadExternalFile removes the objects from map. These functions are supported only in Sygic 2D.
The function is in Sygic3D replaced with LoadGeoFile.
Check details of LoadExternalFile in the reference manual.
The load function supports loading of 2 types of files, Polyline ( see Polyline GF format bellow ) and Geofence (see Geofence RAD format bellow), while setting the second parameter as 1.
Please note this function feature is subject to extra licensing set as geoFiles=yes in a license file.
For help to generate the GF and RAD files see the sections bellow and note there are converters available through Download tools.

Example

This example loads visualization layer on map comprised of geometry objects defined the file MetroLines.gf (see Polyline GF format bellow) and next it loads visualization layer of geofences (see Geofence RAD format bellow).

    import com.sygic.sdk.remoteapi.ApiMaps;
    ...
    try {
        ApiMaps.loadExternalFile("/sdcard/MyGeo/MetroLines.gf", 1, 0);
    } catch (GeneralException e) {
       Log.d("Error", "load gf file error");
    }
    try {
        ApiMaps.loadExternalFile("/sdcard/MyGeo/DangerousZone.rad", 1, 0);
    } catch (GeneralException e) {
       Log.d("Error", "load rad file error");
    }   

ShowCoordinatesOnMap

ShowCoordinatesOnMap opens up the map screen centered at a given position showing the marker on a desired position. The map view can be defined with a zoom level with values between 50 (maximum zoom in) to 30000000 (maximum zoom out) defining the distance from ground in meters of a view. The map dialog can be abandoned with pressing the back button.
Check details of ShowCoordinatesOnMap in the reference manual.

Example

This example opens up the map at a sightseeing point in Bratislava.

        Position pos = new Position(1711671, 4814334);
        try {
            ApiMaps.showCoordinatesOnMap(pos, 1000, 0);
        }
        catch (GeneralException ex)
        {
            Log.d("Error", "show coordinates on map error");
        }

ShowRectangleOnMap

ShowRectangleOnMap opens up the map screen to cover a given rectangle. The map dialog can be abandoned with pressing the back button.
Check details of ShowRectangleOnMap in the reference manual.

Example

This example opens up the map to cover the given rectangle at the center of Prague.

        Rectangle rect = new Rectangle(1441079, 5009388, 1441926, 5008628);
        try {
            ApiMaps.showRectangleOnMap(rect, 0);
        }
        catch (GeneralException ex)
        {
            Log.d("Error", "show rectangle on map error");
        }

SwitchMap

SwitchMap swithces to a new map resources stored under particular folder. With this function one can switch between different map configurations.
Check details of SwitchMap in the reference manual.

Please note the function is intended for offline usage and the Manage maps UI control should be disabled.
Otherwise things can go wrong with map updates being done by end user, i.e. possibly updating an incorrect map folder.
The map updates can potentially be solved with programming approach, i.e. explicitely triggering map updates (e.g. with custom url) making sure the prooper map folder is in use.

Example

This example switches between two map configurations, one representing logistics maps and the other emergency maps.

public void SwitchMap(int mid)
{
    String path = null;
    if (mid == 1) path = "/sdcard/Sygic/maps/logis2018";
    if (mid == 2) path = "/sdcard/Sygic/maps/emerg2018";
    try {
        ApiMaps.switchMap(path, 0);
    } catch (GeneralException e){
        e.printStackTrace();
    }

}

Events

API Events allow capturing of Geofence tresspassing events with a possibility to react on it. The events pass along an associated data denoting identification of the geofence.
The following events are available.

Check for more on Api Events in the reference manual.

Example

import com.sygic.sdk.remoteapi.ApiCallback;
import com.sygic.sdk.remoteapi.events.ApiEvents;
import android.widget.Toast;
...
private Handler mHandler = new Handler();
private ApiCallback mApiCallback = new ApiCallback()
{
    ...

    @Override
    public void onEvent(final int event, final String data)
    {
            mHandler.post(new Runnable() {
               @Override
               public void run() {
                  if (event == ApiEvents.EVENT_GEOFENCE)
                  {
                    int type = GetValue(data, 1);
                    int id = GetValue(data, 2);
                    if (type == 0)
                       Toast.makeText(getApplicationContext(), "entering geofence " + id , Toast.LENGTH_SHORT).show();
                    else
                       Toast.makeText(getApplicationContext(), "leaving geofence " + id , Toast.LENGTH_SHORT).show();   
                  }
               }
            });
    }
};

GF Polyline format

This format allows expression of lines and polylines in the following binary form.

The following rules apply to all the records:

• Multi-byte values are stored with least-significant-byte first.
• Timestamps are specified as (4-byte) unsigned longs, representing seconds since midnight 01/01/1970.
• Coordinates are stored as (4-byte) signed longs, representing WGS84-coordinates in degrees multiplied by 100,000. The coordinates of a point are stored in the order: x, y.
• Strings (including filenames) are stored in ASCII format, they are zero-terminated, and contain at most 254 non-zero characters.
• Rectangles must be "normalized", i.e. the four co-ordinates are in the following sequence: minimum-x, minimum-y, maximum-x, maximum-y.
• Every record must have the same 8-byte "header" and must be a multiple of 4 bytes in length.

The HEADER must be as follows:

1 byte     Type of this record, which is a value between 0 to 127.
           When the most significant bit of this byte is set (>=128),
           it indicates that the record is disabled
3 bytes    Length of this record as a number of 4-byte words,
           Including the 8-byte header
4 bytes    Record ID (for future unique manipulation of this record)

Supported Record Types

TIMESTAMP (type 5): Specifies an "end-of-validity" for all the records that follow it (i.e. until the next timestamp record)

8 BYTES    HEADER
4 bytes    End-of-validity timestamp
4 bytes    Number of bytes (excluding this record itself) that can be
           skipped immediately when end-of-validity is in the past
           (note: this value can be set to 0 if you are lazy)

NOTE: Records NOT preceded by an end-of-validity are "permanently valid." Even so, it is highly recommended that you consider the issue of validity periods, and always make sure that the very first record of the file specifies the end-of-validity for the whole file.

SKIPPER (type 6): Specifies that the coming X bytes relate to a certain rectangle.

8 BYTES    HEADER
16 bytes   Normalized coordinate rectangle of the area
4 bytes    Number of bytes (excluding this record itself) that can be
           skipped if rectangle doesn't overlap the current screen

NOTE: It is highly recommended, in the interest of processing speed, that you always provide a skipper record that specifies the surrounding-rectangle for all the rectangle-dependent records in the whole file together.

IGNORE (type 0): Records with type 0 are completely ignored by the application.

8 BYTES    HEADER
X bytes    Ignored content

NOTE: Uses of this type of record range from permanent deletion (rather than de-activation) of records to watermarking copyright information into your files. However, please be aware that these records still consume memory, and also cost a very short amount of time that can be ignored.

LINE (type 1):

8 BYTES    HEADER
8 bytes    Start coordinates of the line
8 bytes    End coordinates of the line

NOTE: The line type is defined by line thickness. The line thickness codes are:

• 0 - width of road x 1.25
• 2 - width of road
• 6 - width of road x 0.75
• 8 - width of road x 0.5
• 12 - width of road x 0.25

POLYLINE (type 2):

8 BYTES    HEADER
16 bytes   Normalized coordinate rectangle of the area around polyline
4 bytes    Line type (0=default)
4 bytes    Red/Green/Blue color code of lines
4 bytes    N = number of co-ordinates (should be 2 or more)
N*8 bytes  x/y-coordinates of the poly-line

NOTE: The line type field can contain the same codes as in the LINE (type 1) records.

RAD Geofence format

With this binary file you can define special zones. The navigation then provides events about entering or leaving those zones. The zones are displayed with the defined color, and the speed limit warning inside the zone is set to the max allowed speed. The file has to be placed in the folder \Res\geofiles\ during startup of the navigation.
The format example is as follows.