Routing On Map Java

_{Last updated: June 16, 2026 | 5 minutes read}

This is the Java counterpart of the Routing On Map example: it shows how to render an interactive map, compute a route between two points and present the resulting routes on the map. When more than one route is available, every alternative is drawn with a label bubble showing its distance and estimated travel time; tapping an alternative promotes it to the main route and re-centers the map on the whole route collection.

The example keeps the RoutingService inside MainActivity. In a production MVVM app the service would usually live in the repository layer and be consumed by a ViewModel, but for the scope of this example an activity keeps the flow easy to follow.

Routes centered on the map

Alternative route selected

Routing Service

MainActivity retains a single RoutingService instance, created with the default constructor. Its onStarted and onCompleted callbacks are attached later via setOnStarted / setOnCompleted and drive the UI: onStarted shows the progress bar, and onCompleted hides it and then dispatches on the error code - presenting the routes on success, ignoring a cancellation, and surfacing a dialog for any other error. Because the callbacks may arrive after the activity has gone away, the UI work is routed through runOnAliveUi, which posts to the main thread only while the activity is still alive.

MainActivity.javaView on Github

routingService.setOnStarted(hasProgress -> {
    runOnAliveUi(() -> binding.progressBar.setVisibility(View.VISIBLE));
    return null;
});

routingService.setOnCompleted((routes, errorCode, hint) -> {
    runOnAliveUi(() -> {
        binding.progressBar.setVisibility(View.GONE);

        if (errorCode == GemError.NoError) {
            onRoutesReady(routes);
        } else if (errorCode != GemError.Cancel) {
            // Resolve the human-readable error message on the SDK thread via runSynced.
            String errorMessage = GemCall.INSTANCE.runSynced(() -> GemError.INSTANCE.getMessage(errorCode, this));
            showDialog(getString(R.string.routing_completed_with_error, errorMessage), null);
        }
    });
    return null;
});

Calculating the route

Routing needs the worldwide road map to be available, so the calculation is started from the SdkSettings worldwide-road-map status listener once the map data reports EOffboardListenerStatus.UpToDate. The listener clears itself after the first successful fire so the route is computed only once, and it also installs the map touch handler at the same point.

MainActivity.javaView on Github

SdkSettings.INSTANCE.setOnWorldwideRoadMapSupportStatus(status -> {
    if (status == EOffboardListenerStatus.UpToDate) {
        SdkSettings.INSTANCE.setOnWorldwideRoadMapSupportStatus(s -> null);
        calculateRoute();
        setupTouchHandler();
    }
    return null;
});

In calculateRoute() two Landmark instances are defined - one for the departure point and one for the destination. A route needs at least two waypoints, but it may contain more if you want the route to pass through additional intermediate points.

The first waypoint in the list is the departure point and the last is the destination; each Landmark holds a name together with its latitude and longitude in degrees. In this example the route departs from London and arrives in Paris.

The waypoint list is then passed to the routingService to calculate the route. calculateRoute returns synchronously an error code indicating whether the calculation could be started. When it starts successfully the result is delivered later through the service's onCompleted callback; but when it fails to start, that callback never fires - so this case is handled here directly by showing an error dialog.

MainActivity.javaView on Github

private void calculateRoute() {
    GemCall.INSTANCE.execute(() -> {
        ArrayList<Landmark> waypoints = new ArrayList<>();
        waypoints.add(new Landmark("London", 51.5073204, -0.1276475));
        waypoints.add(new Landmark("Paris", 48.8566932, 2.3514616));

        // calculateRoute returns synchronously whether the calculation could be started. On
        // failure onCompleted never fires, so report the error here.
        int errorCode = routingService.calculateRoute(waypoints, null, false, null, null, null);
        if (errorCode != GemError.NoError) {
            String errorMessage = GemError.INSTANCE.getMessage(errorCode, this);
            runOnAliveUi(() -> {
                showDialog(getString(R.string.routing_failed_to_start, errorMessage), null);
            });
        }
        return null;
    });
}

Presenting the routes

When the calculation completes successfully, onRoutesReady stores the returned routes and presents them on the map with presentRoutes. The displayBubble flag draws the distance/time label on each route, while the Animation makes the camera move smoothly. The edgeAreaInsets rectangle keeps the route collection inside the free screen area, clear of the toolbar, the system bars and any display cutout, so no part of a route is hidden behind system UI.

MainActivity.javaView on Github

private void onRoutesReady(ArrayList<Route> routes) {
    routesList = routes;
    GemCall.INSTANCE.execute(() -> {
        MapView mapView = binding.gemSurfaceView.getMapView();
        // Present routes centred within the free screen area, avoiding toolbar and system bars.
        if (mapView != null) {
            mapView.presentRoutes(
                    routes, null, true, true, true, true, true, true,
                    new Animation(EAnimation.Linear, ROUTE_ANIMATION_DURATION_MS, null, null),
                    ERouteDisplayMode.Full, getEdgeAreaInsets()
            );
        }
        return null;
    });
}

Selecting an alternative route

setupTouchHandler registers a map touch listener. When the user taps the map, the touch point is forwarded to the map view as the cursor position, and getCursorSelectionRoutes returns the routes drawn under that point. If the tap lands on a route, the first one is promoted to the main route and the map re-centers on the full route list with centerOnRoutes - using the same animation and a view rectangle that keeps the routes within the visible, system-UI-free area.

MainActivity.javaView on Github

private void setupTouchHandler() {
    MapView mapView = binding.gemSurfaceView.getMapView();
    if (mapView == null) return;

    mapView.setOnTouch(xy -> {
        GemCall.INSTANCE.execute(() -> {
            mapView.setCursorScreenPosition(xy);

            ArrayList<Route> routes = mapView.getCursorSelectionRoutes();
            if (routes != null && !routes.isEmpty()) {
                MapViewPreferences mapViewPreferences = mapView.getPreferences();
                MapViewRoutesCollection routePrefs = mapViewPreferences != null ? mapViewPreferences.getRoutes() : null;

                if (routePrefs != null) {
                    routePrefs.setMainRoute(routes.get(0));
                }

                mapView.centerOnRoutes(
                        routesList, ERouteDisplayMode.Full, getRouteViewRect(),
                        new Animation(EAnimation.Linear, ROUTE_ANIMATION_DURATION_MS, null, null)
                );
            }

            return null;
        });

        return null;
    });
}