Places and coordinates (v2.1.x - Android)

1 Coordinates
2 Places
- 2.1 Addresses
- 2.2 Places of Interest
- 2.3 Images

Coordinates

Geo locations in Navmii SDK are represented as instances of the read-only MapCoordinates class. It has three methods: getLatitude (returns values in the range [-90, 90]), getLongitude (returns values in the range [-180, 180)) and getDistanceTo.

getDistanceTo calculates the distance between the current point and a specified point, returning the result in meters. This method computes the geographical distance using the latitude and longitude values provided in the MapCoordinates object.

Example:

// New York City coordinates
MapCoordinates destination = new MapCoordinates(40.7128, -74.0060);
double distance = currentLocation.getDistanceTo(destination);
System.out.println("Distance: " + distance + " meters");

Navmii SDK also has the MapRectangle class representing a rectangle area on the map. It can be created by specifying its top left and bottom right corners.

// Creates a MapRectangle by specifying top left and bottom right corners
MapCoordinates topLeft = new MapCoordinates(51.50884, -0.12924);
MapCoordinates bottomRight = new MapCoordinates(51.50754, -0.12699);
MapRectangle rectangle = new MapRectangle(topLeft, bottomRight);

Places

Navmii SDK provides a set of classes responsible for representation of addresses an places of interest (POIs). The most basic classes to represent geographical entities are City, State, and Country. City contains the following information on a city:

name
transliterated name
city class (an integer taking values from -1 to 15 and representing the size of the city)
if the city is a capital

Log.i("City", String.format("city name - %s", city.getName()));
Log.i("City", String.format("transliterated city name - %s", city.getTransliteratedName()));
Log.i("City", String.format("city class - %s", city.getCityClass()));
Log.i("City", String.format("is capital - %s", city.isCapital()));

You can retrieve a state's

code
name

from State.

Log.i("State", String.format("state name - %s", state.getName()));
Log.i("State", String.format("state code - %s", state.getCode()));

And from Country you can fetch:

ISO 3 Code
name
extended info

Extended info for a Country is a CountryInfo instance containing in its turn the following information:

country's speed units
country's distance units
country's driving side

Log.i("Country", String.format("country ISO 3 code - %s", country.getIso3Code()));
Log.i("Country", String.format("country name - %s", country.getName()));
Log.i("Country", String.format("country speed units - %s", country.getInfo().getSpeedUnits()));
Log.i("Country", String.format("country distance units - %s", country.getInfo().getDistanceUnits()));
Log.i("Country", String.format("country driving side - %s", country.getInfo().getDrivingSide()));

Addresses

The City, State and Country classes are aggregated into Address class. The Address also provides:

county name
district name
administrative hierarchy
street name
route number
house number

Log.i("Address", String.format("country name - %s", address.getCountry().getName()));
Log.i("Address", String.format("state name - %s", address.getState().getName()));
Log.i("Address", String.format("district name - %s", address.getDistrict()));
Log.i("Address", String.format("county name - %s", address.getCounty()));
Log.i("Address", String.format("city name - %s", address.getCity().getName()));
Log.i("Address", String.format("administrative hierarchy - %s", address.getAdminHierarchy()));
Log.i("Address", String.format("street name - %s", address.getStreet()));
Log.i("Address", String.format("route number - %s", address.getRouteNumber()));
Log.i("Address", String.format("house number - %s", address.getHouseNumber()));

Places of Interest

When working with Navmii SDK search services you will also meet Place instances. They represent places of interest (POIs). A Place instance can provide you with the following info:

POI's name
place type
geographical location
POI's address
a boolean value indicating if the address is approximated
POI data

POI data for a particular place is a PoiData instance containing an integer indicating the place's primary category number and an array with numbers of all categories associated with the place.

Log.i("Place", String.format("place name - %s", place.getName()));
Log.i("Place", String.format("place type - %s", place.getType()));
Log.i("Place", String.format("coordinates - %s", place.getCoordinates()));
Log.i("Place", String.format("address - %s, %s", place.getAddress().getStreet(), place.getAddress().getHouseNumber()));
Log.i("Place", String.format("is address approximated - %s", place.isAddressApproximated()));
Log.i("Place", String.format("POI category - %s", place.getPoiData().getPrimaryCategory()));

for (int category : place.getPoiData().getCategories()) {
    Log.i("Place", "POI belongs to category " + category);
}

A place can also have a display address, which is a string shown to the user. It can be accessed using the Place.getDisplayAddress() method.

Images

A place can have a set of images associated with it. To access them you can use Place.getImages() method, which returns an array of PlaceImage objects containing the following fields:

image URL
thumbnail URL (optional)
image description (optional)