• Optimization
  • Navigation
  • Tracking
  • Maps
  • Places

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

(If you are already aware of the Helper classes, please skip this section and jump to the next section: 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

    public static void fetchRoute(Point origin, Point destination, String lang, NextbillionRoutingCallback callback)
  • Origin + Destination + Request Params Builder + Simplified callback

    public static void fetchRoute(Point origin, Point destination, RouteRequestParams.Builder builder, NextbillionRoutingCallback callback)
  • Origin + Destination + Request Params Builder + Retrofit callback

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

    public static void fetchRoute(Point origin, Point destination, Callback{'<DirectionsResponse>'} callback)
  • Origin + Destination + mode + Retrofit callback

    public static void fetchRoute(Point origin, Point destination, @RequestParamConsts.ValidModes String mode, Callback{'<DirectionsResponse>'} callback)
  • 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)
  • Origin + Destination + Request Params + Retrofit callback

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

Geometry Mode

  • Geometry + GeometryType

    public static void fetchRouteWithGeometry(@NonNull String geometry, @NonNull String geometryType, Callback{'<DirectionsResponse>'} callback)
  • Geometry + GeometryType + Request Params

    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)

    public static void fetchRouteWithGeometry(@NonNull final String geometry, @NonNull final String geometryType, final boolean retry, final Callback{'<DirectionsResponse>'} callback)
  • 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)
  • 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)

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:

Parameter

Required

Type

Format & Usage

Description

baseUrl

Yes

String

Available value:  https://api.nextbillion.io

Base URL to access NextBillion.ai’s route planning feature. The baseUrl can be set using the method Nextbillion.getBaseUri()

mode

Yes

String

Available values: car truck

Represents the mode of transportation. Please note the function RequestParamConsts.MODE_4W can be used to set the mode value.

key

Yes

String

Format: 32 character alphanumeric string



Example: key=API_KEY

API  key for authentication. Please use the method Nextbillion.getAccessKey() to set the key.

language

No

String

Allowed values: en, es, fr, zh, de, ca.

Language of the text instruction Language of the turn-by-turn instructions for route guidance. This parameter accepts two-lettered ISO 639-1 codes to identify the language for instructions. Currently, only the following languages are supported: English(en), Spanish(es), French(fr), Mandarin(zh),German(de), and Catalan(ca). Please note that the method DEFAULT_LANGUAGE_VALUE can be used to set the default language value.

unit

No

String

Allowed values: metric , imperial

The unit system to be used for distance. Users can set the unit value via the RequestParamConsts.METRIC function.

overview

No

String

Allowed values: full, simplified , false.

Output verbosity of overview geometry for the whole trip. Please note that the overview value can be set using the function RequestParamConsts.OVERVIEW_FULL

avoid

No

String

Allowed values: toll , ferry , highway

Objects to avoid on the route.

alternatives

No

Boolean

Default: false

R equest for alternative routes. When   true,  altCount should be greater than 0.

altCount

No

Integer

Default: 0

Number of alternative routes to be returned. Please note the actual number of routes can be smaller than or equal to the provided value.

approaches

No

String

Allowed values; unrestricted, curb Default: unrestricted



Example: approaches=unrestricted;;curb;

A semicolon-separated list indicating the side of the road from which to approach waypoints in a requested route. If provided, the number of approaches must be the same as the number of destinations. However, you can skip a coordinate and show its position in the list with the;

departure _time

No

Integer

The departure times provided in UNIX epoch timestamp in seconds format.

origin

No

String

Starting coordinate of the route.

waypoints

No

String

Example: waypoints=41.349302,2.136480|41.349303,2.136481|41.349304,2.136482

Coordinates along the route betweenorigin and d estination. In case of multiple points please use a pipe (|) as a separator

destination

No

String

Ending coordinate of the route

bearings

No

String

Format: degree1, range1; degree2, range2;…


Example: 90,10; 90 ,10 This means the range is 90-10 and 90+10 degrees.

Limits the search to segments with given bearing, in degrees, towards true north in a clockwise direction.


Each bearings should be in the format of degree,range, where the degree should be a value between [0, 360] and range should be a value between [0, 180].


Note: The number of bearings should equal the number of coordinates.

geometry

No

String

Limits the search to segments with given bearing, in degrees, towards true north in a clockwise direction. Each bearings should be in the format of degree,range , where the degree should be a value between [0, 360] and range should be a value between [0, 180]. Note: The number of bearings should equal the number of coordinates.

geometry _type

No

String

Allowed values: polyline6 ,  polyline .



Default : polyline6

The type of geometry encoding to be used for route in the response. When geometry is provided, this parameter can be used to specify the type of encoded geometry being provided.

below are the default values:

1

mode

RequestParamConsts.MODE_4W

2

overview

RequestParamConsts.OVERVIEW_FULL

3

unit

RequestParamConsts.METRIC

4

key

Nextbillion.getAccessKey()

5

baseUrl

Nextbillion.getBaseUri()

6

alternatives

false

7

altCount

0

8

departureTime

0

9

language

DEFAULT_LANGUAGE_VALUE

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

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


            }
        });

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.

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

Start navigation with the launcher configuration we just built.

NavigationLauncher.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:

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


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

            }
});

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.