Source: https://developers.woosmap.com/products/map-api/guides/directions/ > For clean Markdown of any page, append `.md` to the page URL. > For a complete documentation index, see https://developers.woosmap.com/llms.txt # Get Driving Directions You can calculate directions by using the [`woosmap.map.DirectionsService`](/products/map-api/reference/1.4/#woosmap.map.DirectionsService) object. This object is an interface to the [Route endpoint of Woosmap Distance API](/products/distance-api/features/route/). 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`](/products/map-api/reference/1.4/#woosmap.map.DirectionsRenderer) object to render these results. https://demo.woosmap.com/js-samples/samples/directions-simple/app/dist/ [](https://demo.woosmap.com/js-samples/samples/directions-simple/highlight/highlight.html "Open in new tab with highlighted code") Try sample - [CodeSandbox](https://codesandbox.io/p/devbox/github/woosmap/js-samples/tree/master/dist/samples/directions-simple/app?file=index.ts) - [JsFiddle](https://jsfiddle.net/gh/get/library/pure/woosmap/js-samples/tree/master/dist/samples/directions-simple/jsfiddle) - [Clone on Github](https://github.com/Woosmap/js-samples/tree/sample/directions-simple) ## 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`](/products/map-api/reference/1.4/#woosmap.map.DirectionRequest) 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: ```plaintext { 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](/products/map-api/reference/1.4/#woosmap.map.LatLng) or [LatLngLiteral](/products/map-api/reference/1.4/#woosmap.map.LatLngLiteral). - `destination` (required) specifies the end location to which to calculate directions. This value must be specified as a [LatLng](/products/map-api/reference/1.4/#woosmap.map.LatLng) or [LatLngLiteral](/products/map-api/reference/1.4/#woosmap.map.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: ```javascript 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`](/products/map-api/reference/1.4/#woosmap.map.DirectionResult) and a `DirectionsStatus` code. ```javascript 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](/products/distance-api/features/route/#usage-limits--quotas). ### Direction Result The [`DirectionsResult`](/products/map-api/reference/1.4/#woosmap.map.DirectionResult) 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: 1. Create a new `DirectionsRenderer` object. 2. Call `setMap()` on the renderer to link it to your map object. 3. 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. ```javascript 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](/products/map-api/concepts/polyline-encoding/)). - `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)