# Class Routing

java.lang.Object
com.codename1.maps.routing.Routing

public final class Routing extends Object

The entry point for road-following routes.

A `Polyline` joins the points you give it with straight lines. To draw the road a driver would actually take you need a routing service to work out the road geometry first, which is what this class does:

    MapView map = new MapView();
    Routing.showRoute(map, new LatLng(38.8977, -77.0365), new LatLng(38.8894, -77.0352));

Routing is asynchronous -- the call returns immediately and the line appears once the service answers. For control over the result use `findRoute(RouteRequest, RouteCallback)`:

    Routing.findRoute(new RouteRequest(origin, destination), new RouteCallback() {
        public void routesFound(List routes) {
            Route best = (Route)routes.get(0);
            map.addPolyline(best.toPolyline().setStrokeColor(0xff5722));
            map.fitBounds(best.getBounds(), 40);
            distanceLabel.setText((int)(best.getDistanceMeters() / 1000) + " km");
        }

        public void routeFailed(String message, Throwable error) {
            ToastBar.showErrorMessage(message);
        }
    });

The work is done by a `RouteService`. Unless you install another, that is the keyless `OsrmRouteService` -- read its documentation before shipping, since its default endpoint is a public demo server.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `static void`
  `findRoute(LatLng origin, LatLng destination, RouteCallback callback)`
  Routes from `origin` to `destination` by car and reports the outcome to `callback`.
  `static void`
  `findRoute(RouteRequest request, RouteCallback callback)`
  Routes `request` and reports the outcome to `callback`.
  `static RouteService`
  `getService()`
  The service backing every routing call, creating the default keyless `OsrmRouteService` on first use.
  `static void`
  `setService(RouteService service)`
  Installs the service backing every routing call.
  `static void`
  `showRoute(MapSurface map, LatLng origin, LatLng destination)`
  Draws the best route between `origin` and `destination` on `map` and frames it, with no further code required.
  `static void`
  `showRoute(MapSurface map, RouteRequest request, RouteCallback callback)`
  Draws the best route for `request` on `map`, frames it, and forwards the outcome to `callback`.

  ### Methods inherited from class Object

  `clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- ## Method Details

  - ### getService

    public static RouteService getService()
    The service backing every routing call, creating the default keyless `OsrmRouteService` on first use.

  - ### setService

    public static void setService(RouteService service)
    Installs the service backing every routing call. Pass `null` to restore the default `OsrmRouteService`.

  - ### findRoute

    public static void findRoute(LatLng origin, LatLng destination, RouteCallback callback)
    Routes from `origin` to `destination` by car and reports the outcome to `callback`.

  - ### findRoute

    public static void findRoute(RouteRequest request, RouteCallback callback)

    Routes `request` and reports the outcome to `callback`.

    Returns immediately; `callback` is invoked later on the event dispatch thread, exactly once. A service that reports itself unavailable -- one still waiting for an API key, say -- fails the request here with a readable message instead of letting it turn into a network error, so callers never have to check `RouteService.isAvailable()` themselves.

    Throws `IllegalArgumentException` when `callback` is `null`; an asynchronous call has no other way to reach you.

  - ### showRoute

    public static void showRoute(MapSurface map, LatLng origin, LatLng destination)

    Draws the best route between `origin` and `destination` on `map` and frames it, with no further code required.

    This is the least code that gets you from two coordinates to a line following the roads. Failures are silent -- when you need to report them, or to style the line, use `showRoute(MapSurface, RouteRequest, RouteCallback)`.

    ###### Parameters

    - `map`: the map to draw on

    - `origin`: where the journey starts

    - `destination`: where the journey ends

  - ### showRoute

    public static void showRoute(MapSurface map, RouteRequest request, RouteCallback callback)

    Draws the best route for `request` on `map`, frames it, and forwards the outcome to `callback`.

    The polyline is added and the camera moved before `callback` runs, so the callback can read the route's distance and duration to update the UI. It cannot restyle the line that was drawn -- that polyline is not exposed, and `Route.toPolyline()` hands back a fresh one every call. To control how the route looks, skip this method: call `findRoute(RouteRequest, RouteCallback)` and add the styled polyline yourself.

    ###### Parameters

    - `map`: the map to draw on

    - `request`: the journey to route

    - `callback`: notified of the outcome, or `null` to just draw the route