Work with Distance
Detailed guide on using the DistanceService to calculate distances and durations between multiple origins and destinations or to compute isochrones.
Overview
The DistanceService class is a part of the Woosmap Map
JavaScript API that allows you to calculate distances and durations between multiple origins and destinations. It
provides methods for distance matrix and distance isochrone calculations.
Following operations are supported:
- Distance Matrix lets you calculate distances and durations between multiple origins and destinations.
- Distance Isochrones lets you calculate distance isochrones from a given location.
Review the example below to see how to use the DistanceService and display results using the Woosmap Map JS:
Getting started
Before using the DistanceService in the Map JavaScript API, it is required to have a secure and valid Woosmap API key and enable the Distance API for it.
Next, you must load the Map JS API library by including a script tag in your HTML page as follows:
<script async
src="https://sdk.woosmap.com/map/map.js?key=YOUR_API_KEY&callback=initMap">
</script>
Distance Matrix
Request Distance Matrix
To request a distance matrix calculation, instantiate
a DistanceService object and invoke
DistanceService.getDistanceMatrix(). This method sends a request to the Distance Matrix endpoint of Woosmap Distance
API, using a DistanceMatrixRequest object literal.
The DistanceMatrixRequest object literal contains the following fields:
{
origins: woosmap.map.LatLng[] | woosmap.map.LatLngLiteral[];
destinations: woosmap.map.LatLng[] | woosmap.map.LatLngLiteral[];
method?: "time" | "distance";
elements?: "distance" | "duration" | "duration_distance";
departureTime?: Date | string;
language?: string;
travelMode?: woosmap.map.TravelMode;
unitSystem?: woosmap.map.unitSystem;
avoidFerries?: boolean;
avoidHighways?: boolean;
avoidTolls?: boolean;
avoidZones?: woosmap.map.LatLng[][] | woosmap.map.LatLngLiteral[][];
}
origins: An array containing origins latlng from which to calculate distance and time.destinations: An array containing destinations latlng to which to calculate distance and time.departureTime(Optional): By using this parameter, Distance will calculate the duration with traffic. Specifies the date/time at which to base the calculations on for traffic purposes. Valid values are a Date or a string timestamp or “now”.elements(Optional): Defines element values that will be part of the response (distance and/or duration). If not specified, the default is distance.language(Optional): Defines in which language the results should be returned, if possible.method(Optional): Defines the method to compute the route between the start point and the end point. “time” for the fastest route and “distance” for the shortest route.travelMode(Optional): Specifies the travel mode.unitSystem(Optional): The unit system requested. If not specified, the default is metric.avoidFerries(Optional): If true, instructs the Distance service to avoid ferries where possible.avoidHighways(Optional): If true, instructs the Distance service to avoid highways where possible.avoidTolls(Optional): If true, instructs the Distance service to avoid toll roads where possible.avoidZones(Optional): If set, instructs the Distance service to avoid the specific polygons.
Below is a sample DistanceMatrixRequest for two origins to two destinations using driving mode:
const distanceMatrixRequest = {
origins: [{lat: 45.4642, lng: 9.19}, {lat: 45.75, lng: 4.85}],
destinations: [{lat: 42.6976, lng: 9.45}, {lat: 41.9028, lng: 12.4964}],
travelMode: woosmap.map.TravelMode.DRIVING,
unitSystem: woosmap.map.unitSystem.METRIC,
avoidHighways: true,
avoidTolls: true
};
The DistanceService’s getDistanceMatrix() method is asynchronous and returns
a Promise object that is
either fulfilled with
a DistanceMatrixResponse object upon
successful operation or rejected with an APIError object.
You can attach handlers to this Promise object to process results upon operation success or failure.
const distanceService = new woosmap.map.DistanceService();
distanceService.getDistanceMatrix(distanceMatrixRequest)
.then((response) => {
console.log(response);
})
.catch((error) => {
console.error(error);
});
Distance Matrix Response
The response to a DistanceService.getDistanceMatrix request consists of a status, and a list of
DistanceMatrixResponseRows, one for
each corresponding origin location.
Distance Isochrone
An isochrone is a line that connects points of equal travel time around a given location. Here is a sample of a Distance Isochrone API call using Javascript and displaying the isoline result on Woosmap Map.
Request Distance Isochrone
To request a distance isochrone calculation, instantiate
a DistanceService object and
invoke DistanceService.getDistanceIsochrone(). This method sends a request to the Distance Isochrones endpoint of
Woosmap Distance API, using a DistanceIsochroneRequest object literal.
The DistanceIsochroneRequest object literal contains the following fields:
{
origin: woosmap.map.LatLng | woosmap.map.LatLngLiteral;
value?: number;
language?: string;
method?: "time" | "distance";
travelMode?: string;
unitSystem?: string;
avoidFerries?: boolean;
avoidHighways?: boolean;
avoidTolls?: boolean;
avoidZones?: woosmap.map.LatLng[][] | woosmap.map.LatLngLiteral[][];
};
See Request Distance Matrix for the description of the common fields.
Below is a sample DistanceIsochroneRequest to compute a 10 minutes isochrone from a given location using driving mode:
const distanceIsochroneRequest = {
origin: {lat: 45.4642, lng: 9.19},
travelMode: woosmap.map.TravelMode.DRIVING,
value: 10,
};
The DistanceService’s getDistanceIsochrone() method is asynchronous and returns a Promise object that is either fulfilled with
a DistanceIsochroneResponse object upon successful operation or rejected with an APIError object.
You can attach handlers to this Promise object to process results upon operation success or failure.
const distanceService = new woosmap.map.DistanceService();
distanceService.getDistanceIsochrone(distanceIsochroneRequest)
.then((response) => {
console.log(response);
})
.catch((error) => {
console.error(error);
});
Display Distance Isochrone
The DistanceIsochroneResponse includes
a DistanceIsoline with a path attribute.
This attribute represents the decoded polyline of the isoline, which can be used to visualize the isochrone on the map.
Here is an example of how to display this polyline using the woosmap.map.Polyline layer of the Woosmap Map JS API:
const myMap = new woosmap.map.Map(document.getElementById("map"));
const distanceService = new woosmap.map.DistanceService();
distanceService
.getDistanceIsochrone(distanceIsochroneRequest)
.then(displayIsochrone)
.catch((error) => {
console.error(error);
});
function displayIsochrone(isochrone) {
const polyline = new woosmap.map.Polyline({
path: isochrone.isoline.path,
strokeColor: "#b71c1c",
strokeOpacity: 0.8,
strokeWeight: 4
});
polyline.setMap(myMap);
}
