The SDK supports Android version 2.3.3 ("Gingerbread", API level 10) or higher and the following ABIs:
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); |
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
method, which returns an instance of the MapView.getProjection
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:
setHeading
methodsetTargetLocation
methodsetZoom
methodsetTilt
methodThe 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:
// 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.
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.
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:
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 } |
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_ROUTE
)CHOOSING
)ROUTE_APPLIED
)The SDK can notify listeners on the following route calculation events:
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" , |
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:
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(); |
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:
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
.
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:
"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:
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:
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:
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:
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:
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
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:
Extended info for a Country
is a CountryInfo
instance containing in its turn the following information:
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:
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 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); } |
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:
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); } }); |