Poi API

Overview

Poi API provides POI management functionality for point of interest (POI) objects, being built-in POIs coming with currently installed maps or user-defined POIs.
POIs appear on map, can be visualized with some detail information, and are searchable with search operations.
Concerning user-defined POIs tyou can create or delete categrories through AddPoiCategory and DeletePoiCategory and correspondingly add or delete individual POIs using AddPoi and DeletePoi.
Any type of POI can be subject to search operations, such as search in the vicinity of a given position through FindNearbyPoi, FindNearbyPoiList or a search on route using GetPoiOnRoute.
One can also control visual aspect of various categories through MakeUserPoiVisible or alerting using SetPoiWarning.
The built-in POIs are classified in a predefined categories, example PETROL_STATION, AIRPORT, RESTAURANT, etc.

AddPoiCategory

AddPoiCategory adds a new user-defined category, under which a new set of POIs can be managed. User-defined category is always available across all countries with the same name, and it is not possible to add two categories with a same name.

Check details of AddPoiCategory in the reference manual.

Example

This example creates the new custom POI category "MyPetrolStations" with a dedicated icon given by a png. And it also checks for possible error, e.g. due to duplication.

    try {
        ApiPoi.addPoiCategory("MyPetrolStations", "/sdcard/MyIcons/PetrolStation.png", "DEU", 0);
    } catch (GeneralException e) {
       Log.d("Error", "add category error");
    }

AddPoi

AddPoi adds a new POI into an existing user-defined category. One needs to pay attention to possible duplications, which is not prevented by the function.

Check details of AddPoi in the reference manual.

Example

This example creates a new POI and adds it into the "MyPetrolStations" custom poi category naming it "MyPS-24".

    try {
        Position pos = new Position(1152375, 5105282);
        Poi poi = new Poi(pos, "MyPetrolStations", "MyPS-24", "", false);
        ApiPoi.addPoi(poi, 1000);
    } catch (GeneralException e) {
        Log.d("Error", "add poi error");
    }

GetPoiCategoryList

GetPoiCategoryList retrieves the list of all POI categories contained in the map, inclucing both built-in and user-defined categories.

Check details of GetPoiCategoryList in the reference manual.

Example

This example retrieves the list of all categories and prints their names and the attribute notification distance.

        try {
            ArrayList<PoiCategory> list = ApiPoi.getPoiCategoryList(0);
            for (int i = 0; i < list.size(); i++)
            {
                Log.d("Info", list.get(i).getName());
                Log.d("Info", "" + list.get(i).getNotificationDistance());
            }
        } catch (GeneralException e) {
            Log.d("Error", "get category list error");
        }

GetPoiList

GetPoiList retrieves the list of all POIs of the selected user-defined poi category, based on the POI category name.

Check details of GetPoiList in the reference manual.

Example

This example retrieves the list of the pois of the category MyPetrolStations, and prints their names.

        try {
            ArrayList<Poi> list = ApiPoi.getPoiList("MyPetrolStations", false, 0);
            for (int i = 0; i < list.size(); i++)
            {
                Log.d("Info", list.get(i).getName());
            }
        } catch (GeneralException e) {
            Log.d("Error", "get category list error");
        }

DeletePoiCategory

DeletePoiCategory deletes a user-defined category, as well as all associated POIs underneath. User-defined category is always available across all countries with the same name, so it means the call deletes the category within all countries.

Check details of DeletePoiCategory in the reference manual.

Example

This example deletes the existing custom POI category "MyPetrolStations" and all its POIs. The function result in error if the category does not exist for no country. The country code here is currently redunndant.

        try {
            ApiPoi.deletePoiCategory("MyPetrolStations", "SVK", 1000);
        } catch (GeneralException e) {
            Log.d("Error", "delete category error");
        }

DeletePoi

DeletePoi delete an existing POI from a user-defined category. The POI is deleted based on its identification by category name, poi name and approximate location represented by latitute and longitude.

Check details of DeletePoi in the reference manual.

Example

This example creates a new POI and immediately deletes it.

        // create poi
        Position pos1 = new Position(1714924, 4815223);
        Poi p1 = new Poi(pos1, "MyPetrolStations", "Poi-373", "", false);

        // add poi
        try {
            ApiPoi.addPoi(p1, 0);
        } catch (GeneralException e) {
            Log.d("Error", "cannot add poi");
        }

        Position pos2 = new Position(1714925, 4815224); // approximate location
        Poi p2 = new Poi(pos2, "MyPetrolStations", "Poi-373", "", false);

        // delete poi
        try {
            ApiPoi.deletePoi(p2, 0);
        } catch (GeneralException e) {
            Log.d("Error", "cannot delete poi");
        }

FindNearbyPoi

FindNearbyPoi searches for POI(s) in the vicinity of a given location.
There are two variants of the function, one which returns a single poi, and other returns a list. In case no POI is found the search returns null.

Check details of FindNearbyPoi and FindNearbyPoiList in the reference manual.

Example

This example demonstrates how to find a nearest petrol station around a given location (Karadzicova, Bratislava, Slovakia) and start navigating to it.

import com.sygic.sdk.remoteapi.Api;
import com.sygic.sdk.remoteapi.exception.GeneralException;
import com.sygic.sdk.remoteapi.model.Poi;
import com.sygic.sdk.remoteapi.ApiPoi;
...
try
{
    ArrayList<Poi> mPois = new ArrayList<Poi>(); // arraylist to which we nearby POIs of petrol station category
    int id = 201;              // ID for petrol station category
    String category = "null";  // identifier for custom POIs
    int x = 1712518;           // longitude of Karadzicova, Bratislava, Slovakia
    int y = 4815014;           // latitude of Karadzicova, Bratislava, Slovakia
    int maxTime = 0;           // maximum time function can take, 0 for no time limitation
    int maxCount = 10;
    mPois = ApiPoi.findNearbyPoiList(id, category, x, y, maxCount, maxTime);
    int flags = 0;
    boolean searchAddress = false;
    Position pos = mPois.get(0).getLocation();
    WayPoint wp = new WayPoint();
    wp.SetLocation(pos.getX(), pos.getY());
    ApiNavigation.startNavigation(wp, flags, searchAddress, maxTime);
}
catch (GeneralException e) {
    Log.e("FindPoi", "Error code:" + e.getCode());
}

GetPoiOnRoute

GetPoinOnRoute finds POI candidates on route, which satisfy the constraint of ETA within a given time window.

Check details of GetPoiOnRoute in the reference manual.

Example

This example demonstrates how to find some petrol stations within a driving time interval.
Such a function is typically used to support rest planning, i.e. this function delivers the set of POIs reachable around a required rest stop time.
Please note this function is only available with Sygic 3D navigation.

import com.sygic.sdk.remoteapi.Api;
import com.sygic.sdk.remoteapi.exception.GeneralException;
import com.sygic.sdk.remoteapi.model.Poi;
import com.sygic.sdk.remoteapi.ApiPoi;
...
try
{
    int minutes = 90;                     // number of minutes to drive to the planned stop
    int minDriveTime = minutes*60 - 600;  // lower bound driving time in seconds for the POI search
    int maxDriveTime = minutes*60 + 600;  // upper bound driving time in secndds for the POI search
    int maxTime = 0;                      // maximum time function can take, 0 for no time limitation
    ArrayList pois = ApiPoi.getPoiOnRoute(-1, ApiPoi.PETROL_STATION, minDriveTime, maxDriveTime, maxTime);
    if (pois.size() > 0)
    {
       Position pos = pois.get(0).getLocation();
       WayPoint wp = new WayPoint();
       wp.SetLocation(pos.getX(), pos.getY());
       ApiNavigation.startNavigation(wp, 0, false, maxTime);
    }
}
catch (GeneralException e) {
    Log.e("PoisOnRoute", "Error code:" + e.getCode());
}

SetPoiWarning

SetPoiWarning sets warning on GPS vicinity for both user defined POIs and built-in pois.
For user defined POIs the category needs to be given by its string name, for built-in POIs by string representation of its enumeration value.

Check details of SetPoiWarning in the reference manual.

Example

This example shows how to set navigation warning on user-defined pois of a given category in the vicinity of 300 meters with the predefined sound alert beep. And for built-in pois PETROL_STATIONS the sound alert ring with the vicinity of 200 meters.
Please check all available alerts in the folder Res/sound.

    // user-defined pois
    String categoryName = "MyPetrolStations";
    PoiCategory poicat1 = new PoiCategory(300, false, categoryName, "beep.ogg");
    try {
        ApiPoi.setPoiWarning(poicat1, 0);
    }
    catch (GeneralException ex)
    {
        Log.d("Error", "poi warning error");
    }

    // built-in pois
    String categoryId = "" + ApiPoi.PETROL_STATION;
    PoiCategory poicat2 = new PoiCategory(200, false, categoryId, "ring.ogg");
    try {
        ApiPoi.setPoiWarning(poicat2, 0);
    }
    catch (GeneralException ex)
    {
        Log.d("Error", "built-in poi warning error");
    }   

MakeUserPoiVisible

MakeUserPoiVisible enables or disables a POI category visibility on map for both user defined POIs and/or built-in pois.
For user defined POIs the category needs to be given by its string name, for built-in POIs by its enumeration value.

Check details of MakeUserPoiVisible in the reference manual.

Example

This example shows how to enable visibility on user-defined pois of the category MyPetrolStations and built-in pois of ATMs.


    // user-defined pois
    try{
        ApiPoi.makeUserPoiVisible(ApiPoi.USERDEFINE, "MyPetrolStations", true, 0);
    }
    catch (GeneralException ex)
    {
        Log.d("Error", "user-defined poi visibility error");
    }

    // built-in pois
    try{
        ApiPoi.makeUserPoiVisible(ApiPoi.ATM, null, true, 0);
    }
    catch (GeneralException ex)
    {
        Log.d("Error", "built-in poi visibility error");
    }   

UpdatePois

UpdatePois enables bulk management of user-defined POIs.
The file defines the sequence of actions through new POIs and categories can be added, as well as some existing POIs and categories can be deleted or updated.

Check details of UpdatePois in the reference manual.

Text file format

Each line is a text with one entry. Entry can be a header or a row. The Header specifies the type of following rows, until another header is specified.
The row defines the action of adding/updating or deleting an item, either POI or category.

Headers

...
categories          // following entries will be categories
...
pois                // following entries will be POIs

Category row

+;<id>;<name>;<icon>;<color>  // adds a new category or updates an existing one
-;<id>                        // removes a category if it exists

where:

  • id (int) ... unique ID (must be less than 1000000).
  • name (string) ... display name
  • icon (string) ... full path to image file. This icon will be displayed on map for each POI of this category
  • color (string, optional) ... currently not used

POI row

+;<id>;<name>;<category_id>;<latitude>;<longitude>;<latitude_entry>;<longitude_entry>;<iso>;<color>  // adds a new POI or updates an existing one
-;<id>                                                                                               // removes a POI if exists

where:

  • id (int) ... unique ID
  • name (string) ... display name
  • category_id (int) ... ID of category of this POI
  • latitude, longitude (int) ... location
  • latitude_entry, longitude_entry (int, optional) ... location of entry point
  • iso (string[3]) ... ISO code of the map where this POI is located (currently required)
  • color (string, optional) ... currently not used

Example of file

categories                                             // next lines will be categories
-;1000                                                 // removes category with ID=1000 if it exists
+;1000;Category_1;icons/rupi/melon(5).png;             // adds or updates category
+;1001;2nd cat;icons/rupi/egg(5).png;       
pois                                                   // next lines will be POIs
-;1000                                                 // removes POI with ID=1000 if it exists
-;1001
-;1002
+;1000;Poi_1;1000;4812844;1716525;4812890;1716532;svk; // adds or updates POI
+;1001;Poi_2;1001;4815087;1719732;;;svk;

Example

This example shows the POI database update.

    String update = GetUpdateActionList();
    String res = null;
    try{
        res = ApiPoi.updatePois(update, ApiPoi.FORMAT_TEXT, 0);
    }
    catch (GeneralException ex)
    {
        Log.d("Error", "Poi update error");
    }   

Events

API Events allow monitoring of significant POI events with a possibility to react on it. The events pass along an associated data denoting details of a POI in a structured string.
The following events are available.

Event Associated Data String Description
EVENT_POI_WARNING {poi_category}{poi_name}{lon,lat} occurs when in proximity of a warning-enabled POI within a defined hit radius
EVENT_POI_CLICKED {lon,lat}{poi_category_id}{poi_category_name}{poi_name} occurs when a poi is clicked on map

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_POI_WARNING)
                  {
                    Toast.makeText(getApplicationContext(), data, Toast.LENGTH_SHORT).show();
                  }
               }
            });
    }
};

A possible toast output can be as follows:

  • for user-defined poi
    {mytestpois},{MyPoi-327, Bratislava},{1710751,4814768}
  • for built-in poi
    {201},{OMV Petrol Station 27},{1714637,4814043}