Map Display and Navigation

This section explains the route-to-navigation flow, namely how to define origin/destination, fetch route, and launch navigation.

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

If you already know the helper classes, skip this section and continue to 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,

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

• 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 two modes - Coordinate Mode and Geometry Mode. We cover both of them in following sections:

Coordinate Mode

• Origin + Destination + Simplified callback

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

• Origin + Destination + Request Params Builder + Simplified callback

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

• Origin + Destination + Request Params Builder + Retrofit callback

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

• Origin + Destination + Retrofit callback

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

• Origin + Destination + mode + Retrofit callback

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

• Origin + Destination + mode + unit + Retrofit callback

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

• Origin + Destination + Request Params + Retrofit callback

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

Geometry Mode

• Geometry + GeometryType

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

• Geometry + GeometryType + Request Params

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

• 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)

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

• Geometry + GeometryType + Request Params + Retry (retry mode can rebuild route using first/last geometry coordinates when geometry-based fetch fails.)

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

• 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)

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

Route response callback

As we can tell from the parameters of functions above, there are two different callbacks to receive the fetched routes:

1. NextbillionRoutingCallback is a custom callback interface for handling routing related events in the SDK. The purpose of this callback interface is to simplify routing-related response handling by providing predefined methods for success, failure, or other events.

2. Callback<DirectionsResponse> is a general-purpose callback class used for handling HTTP request responses, specifically tailored to the 'DirectionsResponse' data type in the context of routing.

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):

1
Point origin = Point.fromLngLat(103.75986708439264, 1.312533169133601);
2
Point 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.

1
NBNavigation.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
        });

Use NBNavigation.fetchRoute(origin, destination, callback) to request a route and handle success/failure in the callback.

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.

1
NavLauncherConfig.Builder configBuilder = NavLauncherConfig.builder(route)
2
  .shouldSimulateRoute(true);
3
configBuilder.locationLayerRenderMode(RenderMode.GPS);

Start navigation with the launcher configuration we just built.

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

NavigationLauncher.startNavigation(activity, configBuilder.build()) starts navigation with the built config.

Put them together and we get:

1
NBNavigation.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
                configBuilder.locationLayerRenderMode(RenderMode.GPS);
9
                NavigationLauncher.startNavigation(activity, configBuilder.build());
10
            }
11

12

13
            @Override
14
            public void onFailure(@NonNull Call<DirectionsResponse> call, @NonNull Throwable t) {
15

16
            }
17
});

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.