Location API

Overview

Location API provides geocoding and reverse geocoding functionality, which is to translate an address string into GPS latitude/longitude coordinates and vice-versa.
Geocoding is represented with LocationFromAddress, and reverse geocoding with GetLocationInfo.

The geocoding comes with several options in order to succeed with the translation of not necessarily exact address information. The function has the parameter, which allows switching on so called fuzzy logic, which helps in a translation of adresses containing possible spelling errors. Next, there is the explict function LocationFromAddressEx, which outputs several possible output geocoding candidates ordered in according to matchin score.

The overloaded function GetLocationInfo also returns road attributes of a given location, such as road class, speed restriction, toll classification, etc.

LocationFromAddress

LocationFromAddress translates address into GPS latitude/longitude coordinates.
The input address must be expressed with one of the following patterns:

     country,city,street,house_number
     country,postal_code,street,house_number
     country,zip_code,street,house_number

Optionally the 5th parameter can be added denoting the city district

     country,city,street,house_number,city_district
     country,postal_code,street,house_number,city_district
     country,zip_code,street,house_number,city_district

The decision whether the input contains city or postal code / zip code is the parameter of the function.

Parameter examples

DEU,Berlin,Alexanderplatz,1
SVK,Bratislava,Einsteinova,18
ZAF,Cape Town,Alexandra st,36,Oakdale

The function might return an error, typically due to wrong address format, or missing map.
The country needs to be expressed through a valid ISO code, as an example "DEU" stands for Germany, "GBR" for U.K, "ITA" for Italy, "UCA" for California.
Check details of LocationFromAddress in the reference manual.

Example

This example shows how to translate concrete address into GPS coordinates represented by the LONGPOSITION class object and immediately get navigated to it.
It is possible to make the function more robust with setting the flag fuzzy to true.

using ApplicationAPI;

void demo()
{
    string address = "SVK,Bratislava,Einsteinova,18";
    SError err;
    bool postal = false;
    bool fuzzy = true;
    int maxTime = 0;

    LONGPOSITION location;
    int ret = CApplicationAPI.LocationFromAddress(out err, out location, address, postal, fuzzy, maxTime);
    if (ret == 1)
    {
        int flags = 0;
        bool bShowApplication = true;
        bool bSearchAddress = true;
    SWayPoint wp = new SWayPoint();
    wp.Location.lX = location.lX;
    wp.Location.lY = location.lY;
    CApplicationAPI.StartNavigation(out err, ref wp, flags, bShowApplication, bSearchAddress, maxTime);
    }
}

LocationFromAddressEx

LocationFromAddressEx translates address into a candidate list of address items represented with GPS latitude/longitude coordinates and associated exact and well-formatted address.
In comparison with LocationFromAddress it returns a list of candidates instead of a single best case candidate.
The input address must be expressed with one of the following patterns:

     country,city,street,house_number
     country,postal_code,street,house_number
     country,zip_code,street,house_number

Optionally the 5th parameter can be added denoting the city district

     country,city,street,house_number,city_district
     country,postal_code,street,house_number,city_district
     country,zip_code,street,house_number,city_district

The decision whether the input contains city or postal code / zip code is the parameter of the function.

The output candidates are contained in the list of the class object SWayPoint, which encapsulates both GPS coordinates and an output address. The output address is produced in a one of the following format options:

     country,city,street,house_number
     country,city,street,house_number;district

where district item is output only on maps where available (typically on U.S. maps).

Example

This example shows how to translate concrete address into GPS coordinates represented by the Position class object and immediately print it on a console.
It is possible to make the function more robust with setting the flag fuzzy to true.

using ApplicationAPI;

void demo()
{
        SError err;
    SWayPoint[] arr;
    string address = "SVK,Bratislava,Einst";
    boolean postal = false;
    boolean fuzzy = false;
    int ret = CApplicationAPI.LocationFromAddressEx(out err, address, postal, fuzzy, out arr, maxTime);
    if (ret == 1)
    {
       for (int i = 0; i < arr.length; i++)
       {
          Console.output(arr[i].GetAddress() + " " + arr[i].Location.IX + "," + arr[i].Location.IY );
       }
    }
}

GetLocationInfo for address info

GetLocationInfo translates the GPS coordinates into one of the following address format:

     country,city,street,house_number
     country,city,street,house_number;district

There can be few exceptions occuring with the function call, the most typical one would be an incorrect GPS coordinates or which is out of map coverage.
Check details of GetLocationInfo for address info in the reference manual.

Example

The example returns address of the actual GPS position.

using ApplicationAPI;

void demo()
{
    int lat;
    int lon;
    GetActualGpsPosition(true, out lat, out lon);
    string address = ReverseGeocoding(lat, lon);
    Debug.WriteLine("address:" + address);
}

public void GetActualGpsPosition(bool bSatellitesInfo, out int lat, out int lon)
{
    SError err;
    SGpsPosition gpos = new SGpsPosition();
    int ret = CApplicationAPI.GetActualGpsPosition(out err, out gpos, bSatellitesInfo, 0);
    lat = gpos.Latitude;
    lon = gpos.Longitude;
}

string ReverseGeocoding(int lat, int lon)
{
    string strAddress;
    SError err;
    LONGPOSITION lp = new LONGPOSITION(lon, lat);
    SRoadInfo sri = new SRoadInfo();
    int ret = CApplicationAPI.GetLocationInfo(out err, lp, out strAddress, out sri, 0);
    if (ret != 1)
    {
        return "";
    }
    return strAddress;
}

GetLocationInfo for road info

Overloaded GetLocationInfo returns the road attributes for a given GPS coordinates.
The road attributes are the following:

road class (from RC0 to RC)
speed category
speed restriction
unique identificator of road element (called road offset)
ISO code
yes/no ferry attribute
yes/no prohibited attribute
yes/no toll road attribute
yes/no in congestion charge zone
yes/no paved road
yes/no urban road
yes/no tunnel

Previous article: Init API
Next article: Navigation API