Navmii SDK v.2.0.x for Android

Owned by Roman Teterin (Unlicensed)
Last updated: Nov 15, 2023 by Dmitry Lykov
21 min read


SDK Setup

The SDK supports Android version 2.3.3 ("Gingerbread", API level 10) or higher and the following ABIs:

  • armeabi-v7a
  • arm64-v8a
  • x86
  • x86_64

In order to add the SDK library to your application insert the following code into your app's build.gradle:

repositories {
    maven {
        url '<url>'
    }
}

dependencies {
    compile ('com.navmii.android:navmiisdk:<sdk_version>@aar')
}

Alternatively, if you have the AAR file, you can add it by using the following code:


repositories {
    flatDir {
        dirs '<the_path_to_navmiisdk_aar>'
    }
}

dependencies {
    compile (name: 'navmiisdk:<sdk_version>', ext: 'aar')
}

Add the following lines to the AndroidManifest.xml of your application within the <application></application> block:

<meta-data android:name="com.navmii.sdk.API_KEY" android:value="YOUR_API_KEY" />

Add the following lines to the AndroidManifest.xml within the <manifest></manifest> block:

<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />

The apps targeting Android 5.0 (API level 21) or higher must also include the following line:

<uses-feature android:name="android.hardware.location.gps" />

This version of Navmii SDK doesn't support working with multiple instances of MapView at the same time. The SDK supports only one visible MapView instance at a time. Displaying multiple instances of MapView will result in an undefined behaviour.

The key component of the SDK is a singleton instance of  the Sdk class, which can be received with Sdk.getInstance() static method. To initialize the Sdk and start map rendering use the static Sdk.initSdkAsync method. This method takes ConfigurationSettings as an argument. To deinitialize the SDK use the Sdk.deinitializeSdk method. The Sdk.pause and Sdk.resume methods only start and stop map rendering respectively, without initializing/deinitializing the SDK.

To see code examples of initializing the SDK please refer to Creating the Map View section. ConfigurationSettings are described in SDK Configuration Settings.

Here's the most typical example of the last three methods usage:

    @Override
    protected void onPause() {
        super.onPause();

        Sdk.getInstance().pause();
    }

    @Override
    protected void onResume() {
        super.onResume();

        Sdk.getInstance().resume();
    }

    @Override
    protected void onDestroy() {
        super.onDestroy();

		if (Sdk.getInstance().getState() == Sdk.State.INITIALIZING ||
                Sdk.getInstance().getState() == Sdk.State.INITIALIZED) {

            Sdk.getInstance().deinitializeSdk();
        }
    }


The ConfigurationSettings class represents the settings with which the SDK can be launched. If you have the resources designated to customize the map, you can specify the path to these resources via the setCustomResourcesPath method.

The SDK can use either online or offline map data, this can be selected via the setMapMode method. Call it with Sdk.ConfigurationSettings.MapMode.ONLINE or Sdk.ConfigurationSettings.MapMode.OFFLINE to use online or offline maps, respectively. When offline mode is selected, the path to the folder with maps has to be specified via the setOfflineMapsPath method.

You can also specify the path to the folder where the SDK puts files created at runtime.

To create a ConfigurationSettings instance use the ConfigurationSettings.Builder:

	        Sdk.ConfigurationSettings configurationSettings =
                new Sdk.ConfigurationSettings.Builder()
                        .setOfflineMapsPath(thePath)
                        .build();

When the SDK is configured to use online map data, it uses stable release maps by default. If you need more up-to-date map data, you can use Sdk.ConfigurationSettings.Builder.setUseOnlineBetaMaps(true) method to switch to beta maps. Please note that beta maps may contain errors which are not present in the release ones, therefore it's not recommended to use them in production.

If the SDK is configured to use offline map data, this method has no effect.

The SDK can have four possible states represented by the Sdk.State enum:

  • UNINITIALIZED
  • INITIALIZING
  • INITIALIZED
  • INITIALIZATION_FAILED

The SDK can be used only when it's in INITIALIZED state. You can retrieve the current state through the Sdk.getState method.

The process of the SDK's initialization is asynchronous. To be informed on the initialization finish implement the StateChangeListener interface:

private class SdkStateListener implements Sdk.StateChangeListener {

    // Can only happen between onStart - onStop.
    @Override
    public void onStateChanged(Sdk.State state) {
        switch (state) {
            case UNINITIALIZED:
                break;
            case INITIALIZING:
                break;
            case INITIALIZED:
                break;
            case INITIALIZATION_FAILED:
                break;
        }
    }
}

private final Sdk.StateChangeListener stateChangeListener = new SdkStateListener();

@Override
public void onStart() {
    super.onStart();

    // Check - what if SDK initialization has failed between onStop - onStart.
    if (Sdk.getInstance().getState() == Sdk.State.INITIALIZATION_FAILED) {
        // Show an error message
    }

    Sdk.getInstance().addStateChangeListener(stateChangeListener);

Mapping

In order to add the map view to your activity, insert the following code into the layout file:

<com.navmii.sdk.map.MapView
    android:id="@+id/map_view"
    android:layout_width="match_parent"
    android:layout_height="match_parent" />

Then start the SDK with the Sdk.initSdkAsync static method and after successful initialization pass the map view to it using the setActiveMapView method. After MapView is no longer active you must call setActiveMapView(null).

@Override
public void onStart() {
    super.onStart();

    MapView mapView = (MapView) findViewById(R.id.map_view);

	if (Sdk.getInstance().getState() == Sdk.State.INITIALIZED) {
	    Sdk.getInstance().setActiveMapView(mapView);
	}
}

@Override
public void onStop() {
	super.onStop();

	if (Sdk.getInstance().getState() == Sdk.State.INITIALIZED) {
	    Sdk.getInstance().setActiveMapView(null);
	}
}

You can transform Point representing a screen position of a point on the map to MapCoordinates object representing corresponding GPS location using MapView.getProjection method, which returns an instance of the MapProjection class, and the following code:

MapCoordinates coordinates = mapView.getProjection().mapCoordinatesFromScreenPosition(point);

The reverse operation can be performed by MapProjection.screenPositionFromMapCoordinates:

Point point = mapView.getProjection().screenPositionFromMapCoordinates(coordinates);

For example, to retrieve current GPS position relative to the screen, you can use the following code:

MapCoordinates coordinates = sdk.getNavigationManager().getCurrentPosition();
Point point = mapView.getProjection().screenPositionFromMapCoordinates(coordinates);

Note: south hemisphere latitudes are represented by negative values.

Typically, you want to adjust the area presented on the map on your app's events. You can do it by using MapView.getCameraController method, which returns an instance of the CameraController class, that can be used to move camera to a desired position. The camera position itself is represented in Navmii SDK as CameraPosition. CameraPosition and CameraController allow you to perform the following operations:

  • Setting map rotation via setHeading method
  • Setting map center via setTargetLocation method
  • Setting map zoom via setZoom method
  • Setting map tilt via setTilt method

The CameraPosition is instantiated with a builder:

CameraPosition cameraPosition =
        new CameraPosition.Builder(cameraController.getCameraPosition())
                .setTilt(tilt)
                .setHeading(heading)
                .setZoom(zoom)
                .build();

To move the camera to a position without animation use the CameraController.moveCamera method:

mapView.getCameraController().moveCamera(cameraPosition);

Alternatively, you can set the desired camera position with animation, using one of the three overloaded animateCamera methods. The first one only takes the position. The second one allows you to provide a listener implementing the CameraAnimationListener interface, which will be notified when the animation ends. The last method additionally takes the duration parameter, allowing you to specify the duration of the animation. The default duration is 0.3 seconds.

// Sets the map camera's position with duration of 1.5 seconds
// and logs the result when animation finishes or is canceled
cameraController.animateCamera(cameraPosition, 1.5f, new MapView.CameraAnimationListener() {
    @Override
    public void onAnimationEnded(boolean isCompleted, boolean isCanceled) {
        Log.i("CameraAnimationListener", "onAnimationEnded");
    }
});

To stop current animation use the MapView.stopAnimation method:

mapView.stopAnimation();

The SDK can inform you about camera movements, if you have a class implementing the CameraMovementListener interface and have added an instance of this class to CameraController object's listeners.

There can be three possible reasons for camera movement, defined in the CameraMovementReason enum:

  • gesture;
  • internal animation performed by the SDK (for example, during auto zoom);
  • animation requested by user (see Working with Camera for details).
// Adds ViewController to cameraController's listeners
mapView.getCameraController().addCameraMovementListener(new MapView.CameraMovementListener() {
    @Override
    public void onCameraMoved(CameraMovementReason reason) {
        Log.i("CameraMovementListener", "onCameraMoved, reason: " + reason);
    }
});

You also can add multiple listeners to a CameraController instance. To detach a listener use the removeCameraMovementListener method.

After being created and added to the view hierarchy, MapView is ready to receive the user's touch events. The map reacts to the following gestures as described with no extra code needed.

  • Pan gesture. To drag the map, touch the screen with one finger and hold. Move the finger in the desired direction.
  • Swipe gesture. To move the map with inertia, swipe the screen with one finger. The map will proceed to move in the same direction for a period of time depending on the velocity of the gesture.
  • Pinch gesture. Touch the screen with two fingers and hold. Increase and decrease the distance between them to zoom in and zoom out respectively. Depending on the velocity of the gesture the map can have zoom inertia.
  • Rotation gesture. Touch the screen with two fingers and hold. Rotate the fingers relative to the screen. This gesture also has inertia behaviour.
  • Tilt gesture. Touch the screen with two fingers and move them simultaneously up or down to change the camera tilt.

If you want to handle these gestures in your code please refer to Handling Camera Events section.

MapView recognizes the following gestures without a predefined behaviour. 

  • Single Tap Gesture. Tap the map with one finger once.
  • Double Tap Gesture. Tap the map with one finger twice.
  • Long Press Gesture. Touch the screen with one finger and hold for a period of time.

To process these gesture events make one your classes implement the MapTapListener interface and add it to MapView map tap listeners using the following code:

mapView.addMapTapListener(listener);

You can add multiple map tap listeners to a MapView instance.

This way your object or objects will be notified on these gesture events via the following methods:

@Override
void onSingleTap(MapCoordinates coordinates) {
    // handle single tap
}

@Override
void onDoubleTap(MapCoordinates coordinates) {
    // handle double tap
}

@Override
void onLongTap(MapCoordinates coordinates) {
    // handle long tap
}

Navmii SDK provides an easy way to present custom images on the map and to draw polylines. Children classes of GeoObject abstract class represent these custom images (GeoMarker) and polylines (GeoPolyline) in the SDK. MapView instance is responsible for creating and handling this type of objects.

To present a marker on the map at specified coordinates with default image, instantiate it first by specifying its coordinates and the path to the image and then add it to the map using the MapView.addGeoObject method: 

GeoMarker marker = new GeoMarker(coordinates, imagePath);
mapView.addGeoObject(marker);

To draw a polyline on the map initialize, instantiate it with a list of MapCoordinates representing polyline vertices geo positions and then add it to the map:

GeoPolyline polyline = new GeoPolyline(coordinates);
mapView.addGeoObject(polyline);

You can insert and remove a point or multiple points into and from a polyline, using GeoPolyline's addVertex, removeVertex, removeLastVertex and removeAllVertices methods. To retrieve overall vertices count use the getVertexCount method. To get a copy of all vertices, use the getVertices method.

// Adds a vertex to the polyline's end
polyline.addVertex(coordinates);
// Inserts a vertex into the polyline at index 3
if (polyline.getVertexCount() >= 3) {
    polyline.addVertex(3, coordinates);
}
// Removes last vertex from the polyline
polyline.removeLastVertex();
// Removes the vertex at index 3 from the polyline 
if (polyline.getVertexCount() >= 3) {
    polyline.removeVertex(3);
}
// Removes all vertices from the polyline
polyline.removeAllVertices();

The way the polyline is rendered on the map is also customizable. You can change the polyline's color and width using GeoPolyline's setColor and setWidth methods. The width property is a float value representing polyline's width in density-independent pixels (dp units).

// Sets polyline color to red
polyline.setColor(Color.RED);
// Sets polyline width to 3dp
polyline.setWidth(3);

There are three types of user events related to GeoObject recognized by the SDK:

  • single tap on a geo object
  • double tap on a geo object
  • long press on a geo object

To be able to handle these events make one of your classes implement the GeoObjectListener interface and add an instance of this class to the map view's geo object listeners. Methods onGeoObjectClick, onGeoObjectPress, onGeoObjectRelease and onGeoObjectLongPress will be called on these events:

@Override
void onGeoObjectClick(GeoObject geoObject) {
    // handle click
}

@Override
void onGeoObjectPress(GeoObject geoObject) {
    // handle press
}

@Override
void onGeoObjectRelease(GeoObject geoObject) {
    // handle release
}

@Override
void onGeoObjectLongPress(GeoObject geoObject) {
    // handle long press
}


Routing

The core component responsible for working with routes and navigation in Navmii SDK is RoutingManager. This class's singleton instance allows you to calculate and apply single and multiple routes and receive all necessary navigation information.

If you have a list of MapCoordinates representing waypoints for a route, you can calculate the route (and alternative routes, if applicable) using a RoutePlan instance and calculateRoute method. Alternatively, use calculateRouteFromCurrentPosition method if you you want the route to be calculated from the user's current GPS position. This way you don't need to pass the current position coordinates as the first element in the list of waypoints.

// Creates a RoutePlan instance with waypoints
RoutePlan routePlan = new RoutePlan();
routePlan.setWaypoints(waypoints);
// Calculates routes starting from the first coordinates in the array
sdk.getRoutingManager().calculateRoute(routePlan);
// Performs the same operation but starting with the user's current position
sdk.getRoutingManager().calculateRouteFromCurrentPosition(routePlan);

The methods described above have overloads that accept a RoutingSettings instance as the second parameter. You can use them for customization of route calculation. For more information on RoutingSettings please refer to the Routing Settings section.

// Creates a RoutePlan instance with waypoints
RoutePlan routePlan = new RoutePlan();
routePlan.setWaypoints(waypoints);
// Creates a NMRoutingSettings instance with pedestrian routing mode
RoutingSettings routingSettings = new RoutingSettings.Builder()
        .setRoutingMode(RoutingMode.PEDESTRIAN)
        .build();
// Applies the settings and calculates routes starting from the first coordinates in the array
sdk.getRoutingManager().calculateRoute(routePlan, routingSettings);
// Performs the same operation but starting with the user's current position
sdk.getRoutingManager().calculateRouteFromCurrentPosition(routePlan, routingSettings);

There are three possible RouteManager states that can be obtained with the getStatus method:

  • No routes are presented on the map (NO_ROUTE)
  • A route (or routes) is presented on the map, but the navigation hasn't started (CHOOSING)
  • A route is applied and navigation is in process (ROUTE_APPLIED)

The SDK can notify listeners on the following route calculation events:

  • calculation started
  • calculation succeeded
  • calculation failed
  • route is cleared

To receive these notifications make one of your classes implement the RoutingListener interface and add it to RoutingManager listeners with the following code:

sdk.getRoutingManager().addRoutingListener(listener);

You can add multiple listeners to a RoutingManager instance, so you can have multiple objects notified on route calculation events. You can unsubscribe objects from these notifications using the removeRoutingListener method.

sdk.getRoutingManager().removeRoutingListener(listener);

By default, the SDK calculates up to 3 routes with a particular route plan if possible and renders them on the map. You can disable this type of behaviour with the setDrawAlternativeRoutes method.

// Disables rendering of alternative routes on the map
sdk.getRoutingManager().setDrawAlternativeRoutes(false);

The NSUInteger representing the number of all routes rendered on the map is stored in routesCount property, and the index of the currently selected route is stored in selectedRouteIndex property.

// Logs the numbers of routes and the selected route index
RoutingManager routingManager = sdk.getRoutingManager();
Log.i("RoutingManager", String.format("number of routes %s, selected route index %s", routingManager.getRouteCount(), routingManager.getSelectedRouteIndex()));

To select the route at the desired index use selectRouteAtIndex: method. The clearRoutes method removes all the calculated routes from the map. The abort method cancels route calculation that is currently in progress.

Navmii SDK allows you to customize the parameters that will be used for route calculation via RoutingSettings. You can define if the traffic will be taken into consideration and if toll roads and motorways will be avoided on route calculation:

RoutingSettings routingSettings = new RoutingSettings.Builder()
        .setConsiderTraffic(true)
        .setAvoidTollRoads(true)
        .setAvoidMotorways(true)
        .build();

There are also parameters that define:

  • routing mode (pedestrian or vehicle)
  • optimization type (fastest, easiest, economical, shortest)
  • vehicle type (car, motorcycle, cycle, lorry, truck, delivery truck)

They can be set with setRoutingMode, setRoutingOptimization and setVehicleType methods respectively.

RoutingSettings routingSettings = new RoutingSettings.Builder()
        .setRoutingMode(RoutingMode.VEHICLE)
        .setRoutingOptimization(RoutingOptimization.SHORTEST)
        .setVehicleType(VehicleType.TRUCK)
        .build();

Rerouting

When navigating on the route a better route can be calculated and the currently applied route changed. To enable/disable this option use the RoutingManager.setReroutingEnabled method. There are also two parameters you can specify defining when rerouting is triggered:

  • time difference with possible alternative route
  • length difference with possible alternative route

These parameters can be specified through the RoutingManager.setTimeThresholdForReroutingByTraffic and RoutingManager.setLengthThresholdForReroutingByTraffic methods respectively.

// Enables rerouting when a route 15 minutes faster or 10% shorter is calculated
sdk.getRoutingManager().setReroutingEnabled(true);
sdk.getRoutingManager().setTimeThresholdForReroutingByTraffic(15);
sdk.getRoutingManager().setLengthThresholdForReroutingByTraffic(10);

If you have added a RoutingListener to the RoutingManager, it will be notified on rerouting through onRouteCalculationSucceeded method. In this case the calculationReason parameter will be either REROUTING or REROUTING_CAUSED_BY_TRAFFIC.

Navigation

The main component responsible for navigation in Navmii SDK is NavigationManager. You can access an instance of this class via Sdk.getNavigationManager method:

NavigationManager navigationManager = sdk.getNavigationManager();

Navmii SDK generates various navigation events. To be able to handle these events make one of your classes implement the NavigationListener interface and add an instance of this class to NavigationManager listeners via addNavigationListener method:

navigationManager.addNavigationListener(listener);

You also can add multiple listeners to NavigationManager instance. To detach a listener from NavigationManager instance use removeNavigationListener method.

These navigation events are:

  • change of GPS status
  • change of iOS location services authorization status
  • change of current position
  • update of navigation information (see Navigation Info section)
  • change of country of current location
  • update of guidance info (see Navmii SDK v.2.0.x for Android#Guidance)
  • passing a waypoint
  • reaching the destination
  • demo route start
  • demo route stop

"Passing a waypoint" and "reaching the destination" events correspond to onWaypointPassed and onArrivalPointReached methods respectively:

@Override
void onWaypointPassed() {
    Log.i("NavigationListener", "onWaypointPassed");
}

@Override
void onArrivalPointReached() {
    Log.i("NavigationListener", "onArrivalPointReached");
}

The NavigationManager has the getGpsStatus method indicating if the SDK accepts GPS signal. GPS status is represented as GpsStatus enum of the following values:

  • OK
  • NO_SIGNAL
  • OFF

The onGpsStatusChanged event in NavigationListener interface will be triggered when the status changes:

            @Override
            public void onGpsStatusChanged(GpsStatus status) {
                Log.i("NavigationListener", "onGpsStatusChanged " + status);
            }

The user's current position can be retrieved via NavigationManager.getCurrentPosition method. 

// Logs the user's current position
MapCoordinates currentPosition = navigationManager.getCurrentPosition();
Log.i("NavigationManager", "You are at coordinates: " + currentPosition);

The NMNavigationService listeners will be informed on current position change via onCurrentPositionChanged: method:

            @Override
            public void onCurrentPositionChanged(MapCoordinates coordinates) {
                Log.i("NavigationListener", "onCurrentPositionChanged: " + coordinates);
            }

Navmii SDK allows you to demonstrate the way the real-time traverse of the route will look like on the screen. When the route is calculated, use startDemoRoute and stopDemoRoute methods. Use isDemoRouteActive method to find out if the demo route is still in progress.

// Starts demo route
navigationManager.startDemoRoute();
// Stops demo route
navigationManager.stopDemoRoute();

This is an example of handling demo route start and finish in NavigationListener interface implementation:

    // Logs out messages on demo route start and finish
    @Override
    public void onDemoRouteStarted() {
        Log.i("NavigationListener", "onDemoRouteStarted");
    }

    @Override
    public void onDemoRouteFinished() {
        Log.i("NavigationListener", "onDemoRouteFinished");
    }

Navmii SDK also creates a bitmap image representing traffic on the current route. To be able to receive this image when it updates, make one of you classes implement the TrafficOnRouteImageListener interface and add an instance of this class to NavigationManager's "traffic on route image" listeners:

navigationManager.addTrafficOnRouteImageListener(listener);

To detach a "traffic on route image" listener use removeTrafficOnRouteImageListener method.

@Override
void onTrafficOnRouteImageUpdated(Bitmap bitmap) {
    // handle the image
}

When navigating on the route you can get a NavigationInfo instance from NavigationManager. This object will contain the following information:

  • current road information
  • next road information
  • next direction
  • distance to the next direction in meters
  • speed limit in km/h
  • user's current speed in km/h
  • time to destination point in seconds
  • distance to destination point in meters
  • passed distance in meters
  • country information
  • distance to the next speed camera in meters

To understand how road information is presented in the SDK please refer to Road Info section. Here is an example of code giving you the idea how to retrieve this information:

NavigationInfo navigationInfo = navigationManager.getNavigationInfo();
Log.i("NavigationInfo", String.format("current road name - %s", navigationInfo.getCurrentRoad().getName()));
Log.i("NavigationInfo", String.format("next direction type - %s", navigationInfo.getNextDirection().getDirectionType()));
Log.i("NavigationInfo", String.format("distance to the next direction - %s meters", navigationInfo.getDistanceToDirection()));
Log.i("NavigationInfo", String.format("speed limit - %s kmh", navigationInfo.getSpeedLimit()));
Log.i("NavigationInfo", String.format("current speed - %s kmh", navigationInfo.getCurrentSpeed()));
Log.i("NavigationInfo", String.format("time to destination - %s seconds", navigationInfo.getTimeToDestination()));
Log.i("NavigationInfo", String.format("distance to destination - %s meters", navigationInfo.getDistanceToDestination()));
Log.i("NavigationInfo", String.format("passed distance - %s meters", navigationInfo.getPassedDistance()));
Log.i("NavigationInfo", String.format("country - %s", navigationInfo.getCountry().getName()));
Log.i("NavigationInfo", String.format("distance to speed camera - %s", navigationInfo.getDistanceToSpeedCamera()));


 A RoadInfo instance contains the following information on a road:

  • road name
  • route number
  • form of way
  • functional class

Form of way is represented as FormOfWay enum with this set of values:

  • COMMON
  • RAMP
  • ROUNDABOUT
  • FERRY

An example of code extracting this information from RoadInfo instance can look like this:

RoadInfo roadInfo = navigationInfo.getCurrentRoad();
Log.i("NavigationInfo", String.format("road name - %s", roadInfo.getName()));
Log.i("NavigationInfo", String.format("route number - %s", roadInfo.getRouteNumber()));
Log.i("NavigationInfo", String.format("form of way - %s", roadInfo.getFormOfWay()));
Log.i("NavigationInfo", String.format("functional class - %s", roadInfo.getFunctionalClass()));

Navmii SDK allows you to setup the way the navigation guidance will be provided. It's possible throughout the NavigationManager.getGuidanceSettings method. You can set the guidance output either to text or switch it off. If you pass GuidanceOutput.TEXT to the GuidanceSettings.setGuidanceOutput method, you'll be able to receive String instances with navigation guidance in NavigationListener.onGuidanceTextReady method.

@Override
public void onGuidanceTextReady(String text) {
    Log.i("NavigationListener", "onGuidanceTextReady: " + text);
}


You can also set guidance language via the GuidanceSettings.setLocale method. To get the list of all languages supported by the SDK use the getSupportedLocales method.

// Sets guidance language to American English
GuidanceSettings settings = navigationManager.getGuidanceSettings();
settings.setLocale("en-US");


Currently supported languages:

  • Czech
  • Danish
  • English (UK)
  • English (US)
  • Finnish
  • French (France)
  • German
  • Italian
  • Korean
  • Norwegian
  • Polish
  • Portugese (Brazil)
  • Portugese (Portugal)
  • Russian
  • Spanish (Spain)
  • Swedish
  • Turkish

Places and coordinates

Geo locations in Navmii SDK are represented as instances of the read-only MapCoordinates class. As expected, it has two methods: getLatitude (returns values in the range [-90, 90]) and getLongitude (returns values in the range [-180, 180)). If the values passed to the constructor of MapCoordinates are out of their ranges, they will be adjusted automatically:

  • the latitude is clamped to the range [-90, 90] (e.g. 120 will become 90)
  • the longitude is normalized to the range [-180, 180) (e.g. 195 will become -165)

Navmii SDK also has the MapRectangle class representing a rectangle area on the map. It can be created either by specifying its top left and bottom right corners or by using the MapRectangle.boundingRectangle method. The latter creates a MapRectangle surrounding all the coordinates passed as the argument.

// 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);

// Creates a MapRectangle around all the coordinates in the array
MapCoordinates first = new MapCoordinates(51.50754, -0.12874);
MapCoordinates second = new MapCoordinates(51.50781, -0.12699);
MapCoordinates third = new MapCoordinates(51.50810, -0.12807);
MapCoordinates fourth = new MapCoordinates(51.50839, -0.12924);
MapCoordinates fifth = new MapCoordinates(51.50884, -0.12721);
MapRectangle boundingBox = MapRectangle.boundingRectangle(
        new MapCoordinates[]{first, second, third, fourth, fifth});


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()));

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

  • county 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("statename - %s", address.getState().getName()));
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()));

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);
}

Search

In Navmii SDK it is possible to search addresses and places. You can get a SearchManager instance via getSearchManager method in the Sdk singleton. SearchManager exposes several builders to create the objects needed to perform all possible lookups in the SDK.

SearchManager searchManager = sdk.getSearchManager();

All the classes used for search in the SDK inherit from the Request abstract class. So, all available requests have the following parameters:

  • search location
  • maximum number of search results
  • locale

These parameters can be set via setSearchLocation, setMaxResultCount and setLocale methods of each Request's builder. There is also Request.getStatus method, that allows to get the request's current status represented as RequestStatus enum:

  • NONE
  • PROCEEDING
  • SUCCESS
  • CANCELED
  • FAILED

Request has method start which takes the CompletionListener as an argument, allowing you to pass a listener, which will handle the search results if the request succeeds, or an error in case of failure. You also can cancel the request with the cancel method.

The fastest and the most lightweight request is CountryAndStateRequest. Use this request instead of the ReverseGeocodingRequest when you want to know only country and state at some coordinates. You can create a builder for this request with the SearchManager.createCountryAndStateRequest method. When you perform this search, a List<Place> containing a single item will be returned to the listener.

        Request countryStateRequest =
                searchManager.createCountryAndStateRequest(coordinates).build();

        countryStateRequest.start(new Request.CompletionListener() {
            @Override
            public void onRequestCompleted(Request request, List<Place> results) {
                Address countryAndState = results.get(0).getAddress();
                Log.i("CountryAndStateRequest",
                        String.format(
                                "Request completed: %s %s",
                                countryAndState.getCountry(),
                                countryAndState.getState()));
            }

            @Override
            public void onRequestFailed(Request request, RequestError error) {
                Log.i("CountryAndStateRequest", "Request failed: " + error);
            }
        });

If you want to get the address at some coordinates use ReverseGeocodingRequest. To create a builder for this request use the SearchManager.createReverseGeocodingRequest method.

        Request reverseGeocodingRequest =
                searchManager.createReverseGeocodingRequest(coordinates).build();

        reverseGeocodingRequest.start(new Request.CompletionListener() {
            @Override
            public void onRequestCompleted(Request request, List<Place> results) {
                Log.i("ReverseGeocodingRequest", "Request completed:");

                for (Place place : results) {
                    Log.i("ReverseGeocodingRequest", place.toString());
                }
            }

            @Override
            public void onRequestFailed(Request request, RequestError error) {
                Log.i("ReverseGeocodingRequest", "Request failed: " + error);
            }
        });

Note: if only country and state are relevant for your search please refer to Country and State Search.

You can perform search for Places of Interest (POIs) located within a search radius from some coordinates and containing a specified text string in their names. In order to do this use a PoiRequest instance created via the SearchManager.createPoiRequest. By default, the search is performed within the radius of 100 meters and among all POI categories. You can specify these parameters with setSearchRadius and setPoiCategories methods of the request's builder. Search results in the returned array will be sorted by distance (from closer to farther) from the search location.

        Request poiRequest = searchManager.createPoiRequest("cafe", coordinates).build();

        poiRequest.start(new Request.CompletionListener() {
            @Override
            public void onRequestCompleted(Request request, List<Place> results) {
                Log.i("PoiRequest", "Request completed:");

                for (Place place : results) {
                    Log.i("PoiRequest", place.toString());
                }
            }

            @Override
            public void onRequestFailed(Request request, RequestError error) {
                Log.i("PoiRequest", "Request failed: " + error);
            }
        });

You also can get coordinates for a String representing a particular address. In order to do this use a GeocodingRequest instance, which can be created using the SearchManager.createGeocodingRequest method.

        // Prints coordinates of all found places containing "Piccadilly" in their addresses
        Request geocodingRequest =
                searchManager.createGeocodingRequest("Piccadilly", coordinates).build();

        geocodingRequest.start(new Request.CompletionListener() {
            @Override
            public void onRequestCompleted(Request request, List<Place> results) {
                Log.i("GeocodingRequest", "Request completed:");

                for (Place place : results) {
                    Log.i("ReverseGeocodingRequest", place.toString());
                }
            }

            @Override
            public void onRequestFailed(Request request, RequestError error) {
                Log.i("GeocodingRequest", "Request failed: " + error);
            }
        });