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.
Sygic 2D version uses the function LoadExternalFile and UnloadExternalFile 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.

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.
Check details of LoadGeoFile in the reference manual.
The function is not supported in Sygic2D (please check LoadExternalFile).
This function works with the GeoJSON format, which extends on the specification of GeoJSON.
The function is not released yet. The planned release is October 30, 2017.

Example

This example loads visualization layer on map comprised of geometry objects defined the file EmergencyLayer.json.

    try {
        ApiMaps.loadGeoFile("/sdcard/MyGeo/EmergencyLayer.json", 0);
    } catch (GeneralException e) {
       Log.d("Error", "load 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.

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

Polyline GF 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.

Geofence RAD 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.

Header DWORD "RADF"  
  DWORD Version Set the version to 2
  UINT32 Area count Number of areas defined in the file
  DWORD Area 1 offset Pointer to file position, where Area 1 is defined
  DWORD Area 2 offset  
  DWORD ..  
Area 1 UINT32 Count of points in Area 1 Number of points that
 
  INT32 Area 1 Bounding Rect Left Minimum value of X coordinates defined in points
  INT32 Area 1 Bounding Rect Top Maximum value of Y coordinates defined in points
  INT32 Area 1 Bounding Rect Right Maximum value of X coordinates defined in points
  INT32 Area 1 Bounding Rect Bottom Minimum value of Y coordinates defined in points
  DWORD Offset to Area 1 data Pointer to Point1.X in the file
  DWORD Area 1 color Color to fill the area, in ARGB, set to 0x00FFFFFF for invisible zone
  DWORD Max speed in Area 1 The speed restriction in Area 1 is reduced to this speed (if the original restriction is higher). For no limitations set to zerp. Defined in km/h
  DWORD ID of the Area 1 Set an unique identifier of the area
  DWORD Avoid type of the Area 1 0 area is not avoided, 1 area is avoided/prohibited
Area 1 - data INT32 Point1.X Longitude of the Point1 in degrees multiplied by 100 000
  INT32 Point1.Y Latitude of the Point1 in degrees multiplied by 100 000
  INT32 Point2.X  
  INT32 Pont2.Y  
  INT32 ...  
Area 2 UINT Count of points in Area 2  
  INT32 Area 2 Bounding Rect Left  
  INT32 Area 2 Bounding Rect Top  
  INT32 Area 2 Bounding Rect Right  
  INT32 Area 2 Bounding Rect Bottom  
  DWORD Offset to Area 2 data  
  DWORD Area 2 color  
  DWORD Max speed in Area 2  
  DWORD ID of the Area 2  

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.

Event Associated Data String Description
EVENT_GEOFENCE {event_type}{geofence_id} occurs when geofence is passed. The type is 0 when geofence is entered and 1 when left. The id is the identification of a geofence

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