- Developers
- Professional Navigation for Fleets
- Android
- API
- Location API
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(); }
- Previous article: Init API
- Next article: Navigation API