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 GetLocationAddressInfo.

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.

There is also the function SearchLocation, which provides geocoding as list of candidates from a free text input.

The special function GetLocationRoadInfo 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 exception, 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 Position class object and immediately get navigated to it.
It is possible to make the function more robust with setting the flag fuzzy to true.

import com.sygic.sdk.remoteapi.Api;
import com.sygic.sdk.remoteapi.ApiLocation;
import com.sygic.sdk.remoteapi.ApiNavigation;
import com.sygic.sdk.remoteapi.exception.GeneralException;

void demo()
{
    try {
        String address = "SVK,Bratislava,Einsteinova,18";
        boolean postal = false;
        boolean fuzzy = false;
        Position pos = ApiLocation.locationFromAddress(address, postal, fuzzy, 0);
        WayPoint wp = new WayPoint("B", pos.getX(), pos.getY() );
        ApiNavigation.startNavigation(wp, 0, 0, 0);

    } catch (GeneralException e) {
        Log.e("Error", "Error code:"+ e.getCode());
    }
}

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 Waypoint, 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).

The function might return an exception, 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 LocationFromAddressEx in the reference manual.

Example

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

import com.sygic.sdk.remoteapi.Api;
import com.sygic.sdk.remoteapi.ApiLocation;
import com.sygic.sdk.remoteapi.ApiNavigation;
import com.sygic.sdk.remoteapi.exception.GeneralException;

void demo()
{
    ArrayList<WayPoint> arr;
    try {
        String address = "SVK,Bratislava,Einst";
        boolean postal = false;
        boolean fuzzy = false;
        arr = ApiLocation.locationFromAddressEx(address, postal, fuzzy, 0);

    } catch (GeneralException e) {
        Log.e("Error", "Error code:"+ e.getCode());
    }
    for (int i = 0; i < arr.length; i++)
    {
       Console.output(arr.get(i).getAddr() + " " + arr.get(i).getX() + "," + arr.get(i).getY() )
    }
}

GetLocationAddressInfo

GetLocationAddressInfo 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 GetLocationAddressInfo in the reference manual.

Example

The example returns address of the actual GPS position.

import com.sygic.sdk.remoteapi.ApiLocation;
import com.sygic.sdk.remoteapi.ApiNavigation;
import com.sygic.sdk.remoteapi.model.GpsPosition;
import com.sygic.sdk.remoteapi.exception.GpsException;
import com.sygic.sdk.remoteapi.exception.InvalidLocationException;

void demo()
{
    String addressOut = "";
    try {
        boolean satInfo = false;
        GpsPosition gpsPos = ApiNavigation.getActualGpsPosition(satInfo, 0);
        Position pos = new Position();
        pos.setPosition(gpsPos.getLongitude(), gpsPos.getLatitude());
        addressOut = ApiLocation.getLocationAddressInfo(pos, maxTime);
    } catch (GpsException e) {
        Log.e("GpsPosition", "Error code:"+ e.getCode());
    } catch (InvalidLocationException e) {
        Log.e("Location", "Error code:"+ e.getCode());
    }
    return addressOut;
}

GetLocationRoadInfo

GetLocationRoadInfo 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

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 GetLocationRoadInfo in the reference manual.

SearchLocation

SearchLocation function retrieves list of address candidates from a free text address input.
It may return one to many candidates expressed by lat/lon with a full address info, or returns an error.
The function is built on a callback concept, so it is needed to add a listener object as an input, through which outputs are provided.
The function returns data or error through the callback function OnResult.
Check details of SearchLocation in the reference manual.

Example

This example shows how to perform the search on a free text input. The output is just shown with a popup dialog on screen.
Use examples:

  • Input of "aleksanderplatz" might return { "Aleksanderplatz, Berlin" }

  • Input of "fridrichstrasse" might return { "Fridrichstrasse, Berlin", "Fridrichstrasse, Stuttgart", "Fridrichstrasse, Dresden" }

    
Activity activity;

public void SetActivity(Activity activity)
{
    this.activity = activity;
}

public boolean DoSearch(String searchText)
{
    boolean result = false;
    try {
        result = ApiLocation.searchLocation(searchText, mOnSearchListener, 0);
    } catch (GeneralException e) {
        e.printStackTrace();
    }
    if(!result) {
        return false;
    }
    return true;
}

private OnSearchListener mOnSearchListener = new OnSearchListener() {

    @Override
    public void onResult(String input, ArrayList<WayPoint> waypoints, int resultCode) {
        if(resultCode != OnSearchListener.RC_OK) {
            ShowMessage("<Search problem>");
        }
        else {
            StringBuilder sb = new StringBuilder();
            for(WayPoint wp : waypoints) {
                Position pos = wp.getLocation();

                sb.append(wp.getStrAddress()).append('\n')
                        .append(pos.getX()).append(", ").append(pos.getY())
                        .append("\n\n");
            }

            final String strRes = sb.toString();

            activity.runOnUiThread(new Runnable() {

                @Override
                public void run() {
                    ShowMessage(strRes);
                }
            });
        }
    }
};

private void ShowMessage(String msg)
{
    Toast.makeText(activity, msg, Toast.LENGTH_LONG).show();

}