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

        void AddMyCategory()
        {
            SError err;
            int maxTime = 0;

            int ret = CApplicationAPI.AddPoiCategory(out err, "MyPetrolStations", "PetrolStation.png", "DEU", maxTime);
            if (ret != 1)
            {
                Console.WriteLine("error add category");
                return;
            }
            Console.WriteLine("finish add category");
        }

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

        void AddMyPoi()
        {
            SError err;
            int maxTime = 0;

            var gps = new LONGPOSITION(1152375, 5105282);
            var poi = new SPoi(gps, "MyPetrolStations", "Poi-25", 0);
            int ret = CApplicationAPI.AddPoi(out err, ref poi, maxTime);
            if (ret != 1)
            {
                Console.WriteLine("error add poi");
                return;
            }
            Console.WriteLine("finish add 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 FindNearbyPoi(list) in the reference manual.

Description

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

Example

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

NavigateToNearestPetrolStation(4809159, 1714193);

void NavigateToNearestPetrolStation(int lat, int lon)  // coordinates multiplied by 100 000
{
    SError err;
    SPoi poi = new SPoi();
    int categoryID = (int)PoiService.Petrol_Station;
    string strCategoryName = null;
    int maxTime = 0;
    int flags = 0;

    bool bShowApplication = true;
    bool bSearchAddress = false;
    SWayPoint wp = new SWayPoint();

    int ret = CApplicationAPI.FindNearbyPoi(out err, out poi, categoryID, strCategoryName, lon, lat, maxTime);

    wp.Location.lX = poi.Location.lX;
    wp.Location.lY = poi.Location.lY;

    CApplicationAPI.StartNavigation(out err, ref wp, flags, bShowApplication, bSearchAddress, maxTime);
}

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 shows how to find a petrol station POI on a calculated route at approximately 90 minutes of driving with a tolerance 15 minutes and then get navigated to it.

        void NavigateToPoiOnRoute(int minutes, int radius)
        {
            SError err;
            SPoiOnRoute[] pois;
            int minDriveTime = (minutes - radius) * 60;  // lower bound driving time in seconds for the POI search
            int maxDriveTime = (minutes + radius) * 60;  // upper bound driving time in seconds for the POI search
            int maxTime = 0;
            int ret = CApplicationAPI.GetPoiOnRoute(out err, -1, (int)PoiService.Petrol_Station, minDriveTime, maxDriveTime, out pois, maxTime);
            if (ret == 1 && pois != null)
            {
                if (pois.Length > 0)
                {
                    var poi = pois[0];
                    Console.WriteLine("{0} {1}", poi.GetAddress(), poi.GetName());

                    SWayPoint wp = new SWayPoint();
                    wp.Location.lX = poi.Location.lX;
                    wp.Location.lY = poi.Location.lY;

                    CApplicationAPI.StartNavigation(out err, ref wp, 0, true, false, maxTime);
                    return;
                }

            }
            Console.WriteLine("error get poi");
        }

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