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 POIsCategory row
+;<id>;<name>;<icon>;<color> // adds a new category or updates an existing one
-;<id> // removes a category if it existswhere:
- 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 existswhere:
- 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}
- Previous article: Maps API
- Next article: Settings API
