Get Driving Directions

Get distance, duration and path polyline for a pair of origin and destination, based on the recommended route between those two points for a specified travel mode.

You can calculate directions by using the woosmap.map.DirectionsService object. This object is an interface to the Route endpoint of Woosmap Distance API. This service compute travel distance, time and path for a pair of origin and destination.
You may either display these directions results using custom overlays or use the woosmap.map.DirectionsRenderer object to render these results.

Building Directions Request

To use directions in the Woosmap Map JS API, create an object of type woosmap.map.DirectionsService and call DirectionsService.route() to initiate a request to the Route endpoint of Woosmap Distance API, passing it a DirectionsRequest object literal (containing at least the origin/destination LatLng) and a callback method to process the direction results.

The DirectionsRequest object literal contains the following fields:

        {
  origin: LatLng | LatLngLiteral,
  destination: LatLng | LatLngLiteral,
  travelMode?: string,
  unitSystem?: string,
  provideRouteAlternatives?: boolean,
  waypoints?: DirectionsWayPoint[]
}

origin (required) specifies the start location from which to calculate directions. This value must be specified as a LatLng or LatLngLiteral.
destination (required) specifies the end location to which to calculate directions. This value must be specified as a LatLng or LatLngLiteral.
travelMode (optional) specifies what mode of transport to use when calculating directions. Valid values are specified in Travel Modes below. Default to 'DRIVING'.
unitSystem (optional) specifies what unit system to use when displaying results. Valid values are specified in Unit Systems below. Default to 'Metric'.
waypoints[] (optional) specifies an array of DirectionsWaypoints. Waypoints alter a route by routing it through the specified location(s). A waypoint is specified as an object literal with fields shown below:
provideRouteAlternatives (optional) when set to true specifies that the Route endpoint of Woosmap Distance API may provide more than one route alternative in the response.

Below is a sample DirectionsRequest and a call to route() method:

        const directionsRequest = {
  origin: {lat:48.86288,lng:2.34946},
  destination: {lat:52.52457, lng:13.42347},
  provideRouteAlternatives: false,
  travelMode: woosmap.map.TravelMode.DRIVING,
  unitSystem: woosmap.map.UnitSystem.IMPERIAL, 
  waypoints: [{
    location: {lat:50.84670, lng:4.35684}
  },{
    location: {lat:52.37342, lng:4.84631}
  }]  
}

let directionsService;
directionsService = new woosmap.map.DirectionsService();
directionsService.route(directionsRequest, callback(result, status));

Travel Modes

When you calculate directions, you can specify which transportation mode to use. The following travel modes are currently supported:

TravelMode.DRIVING (Default) calculates driving directions using the road network.
TravelMode.BICYCLING calculates bicycling directions via bicycle and road network.
TravelMode.WALKING calculates walking directions via pedestrian network.

Unit Systems

By default, directions are calculated and displayed using the METRIC unit system. The following unit systems are currently supported:

UnitSystem.METRIC (Default) specifies usage of the metric system. Distances are shown using meters/kilometers.
UnitSystem.IMPERIAL specifies usage of the Imperial (English) system. Distances are shown using miles.

Displaying Directions

Processing a directions request with the route() method of woosmap.map.DirectionsService requires passing a callback called upon service request end. This callback returns a DirectionResult and a DirectionsStatus code.

        let directionsService;
directionsService = new woosmap.map.DirectionsService();
directionsService.route(DirectionRequest, 
                        callback(DirectionResult, DirectionStatus));

Direction Status

The DirectionsStatus may return the following values:

OK indicates the response contains a valid result.
INVALID_REQUEST indicates that the provided request was invalid (e.g. wrong URL syntax).
REQUEST_DENIED indicates that the service denied use of the Distance API service (e.g. wrong API Key, wrong/no referer, …).
UNKNOWN_ERROR indicates a Distance API request could not be processed due to a server error. The request may succeed if you try again.
NOT_FOUND indicates that the origin and/or destination of this pairing could not be matched to the network.
ZERO_RESULTS indicates no route could be found between the origin and destination.
OVER_QUERY_LIMIT (associated to a 429 status code) indicates that the number of queries per second (QPS) exceeds the usage limits.

Direction Result

The DirectionsResult contains the result of the directions query which you can display on the map using the setDirections() method of DirectionsRenderer object.

To display it, follow these steps:

Create a new DirectionsRenderer object.
Call setMap() on the renderer to link it to your map object.
Call setDirections() on the renderer with the DirectionsResult as parameter.

The below example calculates directions between two locations in France. The DirectionsRenderer handles display of the returned polyline (and alternate routes) between the origin and destination.

        const directionsService = new woosmap.map.DirectionsService();
const directionsRenderer = new woosmap.map.DirectionsRenderer();
const map = new woosmap.map.Map(document.getElementById("map"), {
    zoom: 7,
    center: {
      lat: 43.5,
      lng: 2.4
    }
});
directionsRenderer.setMap(map);
directionsService.route({
      origin: {lat:48.86288,lng:2.34946},
      destination: {lat:52.52457, lng:13.42347}
    },
    (response, status) => {
      if (status === "OK") {
        directionsRenderer.setDirections(response);
      } else {
        console.log("Directions request failed with status :" + status);
      }
    }
);

The DirectionsResult Object literal has the routes[] field which contains an array of DirectionsRoute objects. Usually, only one route is returned for a request, unless you set the provideRouteAlternatives field to true, in which several routes may be returned.
Each DirectionsRoute indicates a way to get from the origin to the destination and is composed of the following fields:

overview_polyline represents the polyline of the route (encoded with the polyline algorithm) .
bounds represents the bounding box of the route.
summary to get a readable short name for the route.
legs indicates information about route between waypoints. A route with no waypoints will contain one Leg.

The DirectionsLeg is an object with the following fields:

distance represents the distance of the leg in meters (value) and as text.
duration indicates the duration of the leg in seconds (value) and as text.
start_location indicates the starting location of the leg (it could be different from the given waypoint if there is no road close to it)
end_location indicates the ending location of the leg (it could be different from the given waypoint if there is no road close to it)

‹ Info Window Get Transit Route ›