Map Display and Navigation

This section provides an overview of the core features and capabilities of the Navigation SDK for displaying maps and navigating routes. It covers topics such as starting navigation, using the helper class, defining coordinates and geometries, and handling route response callbacks.

Start a Navigation

The guide explains how to use the SDK to fetch a route and start navigation. It first explains how to fetch a route by providing a pair of coordinates (origin and destination), and then it shows how to use the fetched route(s) to start navigation by building a launch configuration and calling NavigationLauncher.startNavigation().

Helper Class

(You can skip this section and jump to the next one first: Fetch a route) In our navigation SDK, we have put some boilerplate code to start navigations together in NBNavigation to make our life easier. Nextbillion.ai’s Navigation API supports two routing planning modes,

1. Plan route with coordinates: request a route with origin and destination (and middle waypoints if any).

2. Plan a route with geometry string: request a route with geometry data(an encoded polyline)

Below are the function signatures of this helper class, and it is naturally grouped by 2 modes(coordinate mode and geometry mode): Coordinates mode

Coordinates mode

1. Origin + Destination + Simplified callback

   1public static void fetchRoute(Point origin, Point destination, String lang, NextbillionRoutingCallback callback)

   Copied
2. Origin + Destination + Request Params Builder + Simplified callback

   public static void fetchRoute(Point origin, Point destination, RouteRequestParams.Builder builder, NextbillionRoutingCallback callback)

   Copied
3. Origin + Destination + Request Params Builder + Retrofit callback

   public static void fetchRoute(Point origin, Point destination, RouteRequestParams.Builder builder, Callback{'<DirectionsResponse>'} callback)

   Copied
4. Origin + Destination + Retrofit callback

   1public static void fetchRoute(Point origin, Point destination, Callback{'<DirectionsResponse>'} callback)

   Copied
5. Origin + Destination + mode + Retrofit callback

   public static void fetchRoute(Point origin, Point destination, @RequestParamConsts.ValidModes String mode, Callback{'<DirectionsResponse>'} callback)

   Copied
6. Origin + Destination + mode + unit + Retrofit callback

   public static void fetchRoute(Point origin, Point destination, @RequestParamConsts.ValidModes String mode, @RequestParamConsts.SupportedUnits String unit, Callback{'<DirectionsResponse>'} callback)

   Copied
7. Origin + Destination + Request Params + Retrofit callback

   public static void fetchRoute(Point origin, Point destination, RouteRequestParams params, Callback{'<DirectionsResponse>'} callback)

   Copied

Geometry Mode

1. Geometry + GeometryType

   public static void fetchRouteWithGeometry(@NonNull String geometry, @NonNull String geometryType, Callback{'<DirectionsResponse>'} callback)

   Copied

2. Geometry + GeometryType + Request Params

   public static void fetchRouteWithGeometry(@NonNull String geometry, @NonNull String geometryType, @NonNull RouteRequestParams params, Callback{'<DirectionsResponse>'} callback)

   Copied

3. Geometry + GeometryType + Retry (once retry is true and failed to retrieve route based on geometry, the SDK will populate the first and last coordinates from geometry to re-fetch a route)

   public static void fetchRouteWithGeometry(@NonNull final String geometry, @NonNull final String geometryType, final boolean retry, final Callback{'<DirectionsResponse>'} callback)

   Copied

4. Geometry + GeometryType + Request Params + Retry (once retry is true and failed to retrieve route based on geometry, the SDK will populate the first and last coordinates from geometry to re-fetch a route)

   public static void fetchRouteWithGeometry(@NonNull final String geometry, @NonNull final String geometryType, @NonNull final RouteRequestParams params, final boolean retry, final Callback{'<DirectionsResponse>'} callback)

   Copied

5. Geometry + GeometryType + Origin + Destination (once we failed to retrieve a route based on geometry, the SDK will re-fetch a route with the provided origin and destination coordinates)

   public static void fetchRouteWithGeometry(@NonNull final String geometry, @NonNull final String geometryType, @NonNull final Point origin, @NonNull final Point destination, final Callback{'<DirectionsResponse>'} callback)

   Copied

Route response callback

As we can tell from the parameters of functions above, there are two different callbacks to receive the fetched routes, NextbillionRoutingCallback and Callback<DirectionsResponse>. NextbillionRoutingCallback is a simplified callback function that Callback<DirectionsResponse> is the default Retrofit HTTP call’s callback function, which allows developers to handle everything by themselves.

Request Parameters

RouteRequestParams is a data structure that allows developers to modify the parameters of route planning, which includes parameters:

below are the default values:

Fetch a route

The minimum requirement to fuel a route fetching is a pair of coordinates, an origin point, and a destination point, in this docs, we are using two fixed coordinates(In Singapore):

1Point origin = Point.fromLngLat(103.75986708439264, 1.312533169133601);
2Point destination = Point.fromLngLat(103.77982271935586, 1.310473772283314);

And then utilize the functions from “NBNavigation”.

The simplest function/static method only requires three parameters, two coordinates, and an instance of the Retrofit’s Callback, with this function, we can populate the response and get the route instance, we are also able to handle HTTP status code and errors by ourselves.

1NBNavigation.fetchRoute(origin, destination, new Callback<DirectionsResponse>() {
2            @Override
3            public void onResponse(@NonNull Call<DirectionsResponse> call, @NonNull Response<DirectionsResponse> response) {
4                DirectionsRoute route = response.body().routes().get(0);
5                //start navigation with the route we just fetched.
6            }
7
8            @Override
9            public void onFailure(@NonNull Call<DirectionsResponse> call, @NonNull Throwable t) {
10
11
12            }
13        });

The code snippet above is utilizing the NBNavigation.fetchRoute() method to retrieve a route between a given origin and destination coordinates. The method takes in 3 parameters, origin and destination coordinates and a callback object.

The callback object provides two observer methods, onResponse() and onFailure() for handling the API response. In case of a successful API call, the method onResponse() will be invoked, in which we can retrieve the first route from the response and save it in the variable route. Subsequently, it initiates navigation with this route.

On the other hand, if there is a failure in the API call, the method onFailure() will be executed, it can be used to handle the exception or display an error message to the developer/user.

Start navigation

After we fetch a route, the next step is to build a launching configuration that is composed of a route and set shouldSimulateRoute as true if we want to simulate the navigation.

1NavLauncherConfig.Builder configBuilder = NavLauncherConfig.builder(route)
2.shouldSimulateRoute(true);

Start navigation with the launcher configuration we just built.

1NavigationLauncher.startNavigation(activity, configBuilder.build());

This line of code will start the navigation using the NavigationView, the parameter activity here is the context of the current activity from which the navigation is starting, and the config object is provided by the builder method.

Put them together and we get:

1NBNavigation.fetchRoute(origin, destination, new Callback<DirectionsResponse>() {
2            @Override
3            public void onResponse(@NonNull Call<DirectionsResponse> call, @NonNull Response<DirectionsResponse> response) {
4                DirectionsRoute route = response.body().routes().get(0);
5                //start a navigation with the route we just fetched.
6               NavLauncherConfig.Builder configBuilder = NavLauncherConfig.builder(route)
7 .shouldSimulateRoute(true);
8               NavigationLauncher.startNavigation(this, configBuilder.build());
9            }
10
11
12            @Override
13            public void onFailure(@NonNull Call<DirectionsResponse> call, @NonNull Throwable t) {
14
15            }
16});

It is assumed that the developer, who integrates this piece of code, already has the SDK set up and configured correctly, the import classes and interfaces are already added and the developer has the required permissions to start the navigation.