Distance Matrix endpoint
How to compute travel distance and time for a matrix of origins and destinations.
- Required parameters
- Optional parameters
- Traffic awareness parameter (optional)
- Distance Matrix example
- Response
- Distance API server side
- Usage limits
- Example
- Support of POST method
Get distances and durations for a matrix of origins and destinations, based on the recommended route between start and end points for a specified travel mode. The API returns information consisting of rows containing distance and duration values for each pair of start and end point. The returned distances are designed to be used to find and sort multiple assets by road distance. Duration values are either based on average speed, or with traffic awareness according to request parameters.
Requests should be build as follow:
https://api.woosmap.com/distance/distancematrix/json?parameters
Required parameters
Some parameters are required to initiate a Distance Matrix API request. As it is standard in URLs, all parameters are separated using the ampersand (&) character. The list of parameters and their possible values are enumerated below.
https://api.woosmap.com/distance/distancematrix/json?origins=48.836,2.237&destinations=48.709,2.403|48.768,2.338|enc:gbxhHoo}M:|49.987,2.223&key={PUBLIC_API_KEY}
origins
The starting point for calculating travel distance. You can supply one or more locations separated by the pipe character (|), in the form of latitude/longitude coordinates. They are used unchanged to calculate distance. Ensure that no space exists between the latitude and longitude values.
destinations
One or more locations to use as the finishing point for calculating travel distance. The options for the destinations parameter are the same as for the origins parameter, described above.
In order to reduce URL size, encoded polylines are also supported for origins and destination using enc:encoded-polyline:
key
Your project’s API key. This key identifies your Woosmap Project for purposes of quota management. (you should use key client side and private_key server side)
Please refer to the documentation to get an API Key if necessary
Optional parameters
.../distance/distancematrix/json?origins=48.836,2.237&destinations=48.709,2.403|48.841,2.328|48.823,2.326|48.768,2.338|49.123,2.524|48.789,2.456|49.987,2.223&key=[APIKey]&mode=driving&language=en&units=metrics
mode
Specifies the mode of transport to use when calculating distance. Valid values are driving, cycling, walking. (if not specified default is driving)
language
The language code, indicating in which language the results should be returned, if possible. If language is not supplied, the Distance API service will use the navigator language or “en”.
units
Specifies the unit system to use when expressing distance as text. Two different units supported:
| units=metric | (default) returns distances in kilometers and meters |
| units=imperial | returns distances in miles and feet |
elements
Specifies element values that will be part of the API response (distance and/or duration). Valid values are distance, duration, duration_distance (if not specified default is distance)
method
Specifies the method to compute the route between elements:
time: fastest route (default)distance: shortest route
avoid
Specifies features and/or zones to avoid when computing a route.
- A feature to avoid is given by its name, features currently supported are:
tolls: Find a route that does not pass through toll segments.highways: Find a route that does not pass through highway segments.ferries: Find a route that does not pass through ferry segments.
Note that sometimes ferries, highways or toll are required to complete a route so setting those parameters are not guaranteed to avoid them entirely.
- A zone to avoid is given as a polygon, formed by a list of coordinates:
- You need to give at least 3 coordinates for each zone
- Each coordinate is separated by a semi-column (
;) - A coordinate is given in the form of a couple of latitude,longitude.
- You can mix features and zones, using the pipe (
|) separator - Limitation : the total perimeter of each zone can not exceed 10km.
example : avoid=tolls|42.2345,2.4536;42.35664,2.66736;43.34534,3.25534|42.5543,2.2565;42.67764,2.5625;43.6736,3.5545
Traffic awareness parameter (optional)
To get matrix calculation taking into account live traffic conditions, historical traffic patterns, or time-dependent restrictions, you can either use the departure_time.
departure_time
Specifies the date/time at which to base the calculations on for traffic purposes.
Valid values are timestamp or now.
e.g. 22/09/2020 20:26:13 ==> 1600799173
To benefit from traffic data, you must enable the “Distance with traffic” addon.
Distance Matrix example
The following example requests the distance matrix between a pair of origins to one destination, using the distance
method and retrieving the duration_distance in response with imperial unit system. Request is done with the POST method:
https://api.woosmap.com/distance/distancematrix/json
?private_key=YOUR_PRIVATE_API_KEY
curl -L -X POST 'https://api.woosmap.com/distance/distancematrix/json?private_key=YOUR_PRIVATE_API_KEY' \
-H 'content-type: application/json' \
--data-raw '{
"origins": "48.73534,2.368308|48.73534,2.368308",
"destinations": "48.83534,2.368308",
"units": "imperial",
"elements": "duration_distance",
"method": "distance",
"departure_time": "now"
}'
var axios = require('axios');
var data = JSON.stringify({
"origins": "48.73534,2.368308|48.73534,2.368308",
"destinations": "48.83534,2.368308",
"units": "imperial",
"elements": "duration_distance",
"method": "distance",
"departure_time": "now"
});
var config = {
method: 'post',
url: 'https://api.woosmap.com/distance/distancematrix/json?private_key=YOUR_PRIVATE_API_KEY',
headers: {
'content-type': 'application/json'
},
data : data
};
axios(config)
.then(function (response) {
console.log(JSON.stringify(response.data));
})
.catch(function (error) {
console.log(error);
});
import requests
import json
url = "https://api.woosmap.com/distance/distancematrix/json?private_key=YOUR_PRIVATE_API_KEY"
payload = json.dumps({
"origins": "48.73534,2.368308|48.73534,2.368308",
"destinations": "48.83534,2.368308",
"units": "imperial",
"elements": "duration_distance",
"method": "distance",
"departure_time": "now"
})
headers = {
'content-type': 'application/json'
}
response = requests.request("POST", url, headers=headers, data=payload)
print(response.text)
OkHttpClient client = new OkHttpClient().newBuilder()
.build();
MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\n \"origins\": \"48.73534,2.368308|48.73534,2.368308\",\n \"destinations\": \"48.83534,2.368308\",\n \"units\": \"imperial\",\n \"elements\": \"duration_distance\",\n \"method\": \"distance\",\n \"departure_time\": \"now\"\n}");
Request request = new Request.Builder()
.url("https://api.woosmap.com/distance/distancematrix/json?private_key=YOUR_PRIVATE_API_KEY")
.method("POST", body)
.addHeader("content-type", "application/json")
.build();
Response response = client.newCall(request).execute();
require "uri"
require "json"
require "net/http"
url = URI("https://api.woosmap.com/distance/distancematrix/json?private_key=YOUR_PRIVATE_API_KEY")
https = Net::HTTP.new(url.host, url.port)
https.use_ssl = true
request = Net::HTTP::Post.new(url)
request["content-type"] = "application/json"
request.body = JSON.dump({
"origins": "48.73534,2.368308|48.73534,2.368308",
"destinations": "48.83534,2.368308",
"units": "imperial",
"elements": "duration_distance",
"method": "distance",
"departure_time": "now"
})
response = https.request(request)
puts response.read_body
Response
Distance provides a JSON response containing the following root elements:
status contains metadata on the request. See Status Codes below.
rows contain an array of elements, which in turn each contain a status, distance and duration element.
{
"status": "OK",
"rows":
[
{
"elements":
[
{
"status": "OK",
"duration": { "value": 1248, "text": "21 mins" },
"distance": { "value": 12221, "text": "7.6 miles" },
},
],
},
{
"elements":
[
{
"status": "OK",
"duration": { "value": 1248, "text": "21 mins" },
"distance": { "value": 12221, "text": "7.6 miles" },
},
],
},
],
}
Status Codes
OK indicates the response contains a valid result.
INVALID_REQUEST indicates that the provided request was invalid (e.g. wrong URL syntax).
MAX_ELEMENTS_EXCEEDED indicates that the product of origins and destinations exceeds the per-query limit (fixed at 200 elts/q).
MAX_ROUTE_LENGTH_EXCEEDED indicates that at least one of requested route is too long and the matrix cannot be processed (>500km).
REQUEST_DENIED indicates that the service denied use of the Distance API service (e.g. wrong API Key, wrong/no referer, …).
BACKEND_ERROR indicates a Distance API request could not be processed due to a server error. This may indicate that an origin and/or destination of the matrix could not be snapped to the network, does not respect some usage limits or that no route could be found that respects the avoid option.
OVER_QUERY_LIMIT (associated to a 429 status code) indicates that the number of queries per second (QPS) or the number of elements per second (EPS) exceed the usage limits
Elements
Each element contains the following fields:
status: See Status Codes for a list of possible status codes.
distance: The total distance of this route, expressed in meters (value) and as text. The textual value uses the unit system specified with the units parameter of the original request.
duration: The total duration to travel this route, expressed in seconds (value) and as text. The textual value gives a structured string for duration in the specified language (if available).
Elements Status Codes
OK indicates the response contains a valid result.
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.
Distance API server side
As for other Woosmap APIs, if you plan to use Distance API sever side you must use a private_key in your requests.
.../distance/distancematrix/json?origins=48.836,2.237&destinations=48.709,2.403|48.841,2.328|48.823,2.326|48.768,2.338|49.123,2.524|48.789,2.456|49.987,2.223&private_key=[Private APIKey]&mode=driving&language=en&units=metrics
Usage limits
The following usage limits are in place for the Distance API:
- Maximum 200 elements per client-side or server side request.
- Maximum of 10 queries per second (QPS) per Project (so possibly the sum of client-side and server-side queries)
- 1000 elements per second (EPS) per Project, calculated as the sum of queries for one Woosmap Project (so possibly the sum of client-side and server-side queries).
- Max distance between origins and destinations should not exceed 500km.
Example
Here is a sample of a Distance API call using Javascript. It queries Distance Matrix through woosmap.map.DistanceService to get distances and durations between couples of origins and destinations.
Support of POST method
If the URL size is too short for your origins and destinations, you could also request the server using POST method and passing arguments as json.
https://api.woosmap.com/distance/distancematrix/json
?private_key=YOUR_PRIVATE_API_KEY
curl -L -X POST 'https://api.woosmap.com/distance/distancematrix/json?private_key=YOUR_PRIVATE_API_KEY' \
-H 'content-type: application/json' \
--data-raw '{
"origins": "48.73534,2.368308|48.73534,2.368308",
"destinations": "48.83534,2.368308",
"units": "imperial",
"elements": "duration_distance",
"method": "distance",
"departure_time": "now"
}'
var axios = require('axios');
var data = JSON.stringify({
"origins": "48.73534,2.368308|48.73534,2.368308",
"destinations": "48.83534,2.368308",
"units": "imperial",
"elements": "duration_distance",
"method": "distance",
"departure_time": "now"
});
var config = {
method: 'post',
url: 'https://api.woosmap.com/distance/distancematrix/json?private_key=YOUR_PRIVATE_API_KEY',
headers: {
'content-type': 'application/json'
},
data : data
};
axios(config)
.then(function (response) {
console.log(JSON.stringify(response.data));
})
.catch(function (error) {
console.log(error);
});
import requests
import json
url = "https://api.woosmap.com/distance/distancematrix/json?private_key=YOUR_PRIVATE_API_KEY"
payload = json.dumps({
"origins": "48.73534,2.368308|48.73534,2.368308",
"destinations": "48.83534,2.368308",
"units": "imperial",
"elements": "duration_distance",
"method": "distance",
"departure_time": "now"
})
headers = {
'content-type': 'application/json'
}
response = requests.request("POST", url, headers=headers, data=payload)
print(response.text)
OkHttpClient client = new OkHttpClient().newBuilder()
.build();
MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\n \"origins\": \"48.73534,2.368308|48.73534,2.368308\",\n \"destinations\": \"48.83534,2.368308\",\n \"units\": \"imperial\",\n \"elements\": \"duration_distance\",\n \"method\": \"distance\",\n \"departure_time\": \"now\"\n}");
Request request = new Request.Builder()
.url("https://api.woosmap.com/distance/distancematrix/json?private_key=YOUR_PRIVATE_API_KEY")
.method("POST", body)
.addHeader("content-type", "application/json")
.build();
Response response = client.newCall(request).execute();
require "uri"
require "json"
require "net/http"
url = URI("https://api.woosmap.com/distance/distancematrix/json?private_key=YOUR_PRIVATE_API_KEY")
https = Net::HTTP.new(url.host, url.port)
https.use_ssl = true
request = Net::HTTP::Post.new(url)
request["content-type"] = "application/json"
request.body = JSON.dump({
"origins": "48.73534,2.368308|48.73534,2.368308",
"destinations": "48.83534,2.368308",
"units": "imperial",
"elements": "duration_distance",
"method": "distance",
"departure_time": "now"
})
response = https.request(request)
puts response.read_body
The API Key should still be pass as URL argument
