Route endpoint
How to compute travel distance, time and path for a pair of origin and destination.
- Required parameters
- Optional parameters
- Traffic awareness parameters (optional)
- Route example
- Response
- Route endpoint server side
- Usage limits
- Example
Get distance, duration and path (as a polyline) between an origin and a destination, based on the recommended route between those two points for a specified travel mode. This endpoint provides you all the information needed to evaluate an itinerary and display it on a map. You can either retrieve duration values based on average speed, or with traffic awareness according to request parameters.
Requests should be build as follows:
https://api.woosmap.com/distance/route/json?parameters
Required parameters
Some parameters are required to initiate a Distance Route 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/route/json?destination=47.852954,2.290887&origin=49.850077,4.311124&key={PUBLIC_API_KEY}
origin
The starting point for the route. It should be supplied in the form of latitude/longitude coordinates. Ensure that no space exists between the latitude and longitude values.
destination
The ending point for the route. It should be supplied in the form of latitude/longitude coordinates. Ensure that no space exists between the latitude and longitude values.
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
https://api.woosmap.com/distance/route/json?origin=49.850077,4.311124&destination=47.852954,2.290887&mode=driving&language=ru&units=imperial&alternatives=true&details=full&key={PUBLIC_API_KEY}
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: metric(default) returns distances in kilometers and meters, imperial returns distances in miles and feet.
alternatives
Specifies if alternative routes should be returned. Valid values are true and false (default is false). Depending on the calculated route, alternatives may not be provided.
The routes are sorted by time or duration depending on the method parameters ( default is duration ).
The recommended route will have the value recommended: true in the response.
waypoints
A list of points by which the route should pass (route response is divided into legs, one leg corresponding to a route between two waypoints). Waypoints should be separated by | character.
Optionally, you may pass optimize:true as the first argument within the waypoints parameter. This way the provided route is optimized by rearranging the waypoints in a more efficient order based on distance or time according to the method parameter. The route start point and end point order is not changed, their position is considered fixed.
example : waypoints=optimize:true|48.850077,3.311124|48.850077,3.411124
alternatives and waypoints can not be used at the same time.
method
Specifies the method to compute the route between the start point and the end point:
time: fastest route (default)distance: shortest route
details
Specifies if maneuver instructions should be returned (roadbook). Valid values are none and full (default is none)
This parameter has no effect if used combined with Traffic awareness parameters. No maneuver instructions available when requesting traffic awareness.
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|highways|42.23,2.45;42.35,2.66;43.34,3.25
Traffic awareness parameters (optional)
To get route calculation taking into account live traffic conditions, historical traffic patterns, or time-dependent restrictions, you can either use the departure_time or arrival_time parameters.
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
Use either arrival_time or departure_time, not both.
By using this parameter, duration is calculated taking into account the traffic
arrival_time
Specifies the date/time at which to base the calculations on for traffic purposes.
Valid values are timestamp.
e.g. 22/09/2020 20:26:13 ==> 1600799173
Use either arrival_time or departure_time, not both.
By using this parameter, duration is calculated taking into account the traffic
To benefit from traffic data, you must enable the “Distance with traffic” addon.
Route example
The following example requests the route between an origin to a destination, using the distance
method and driving mode and retrieving the response with en language:
https://api.woosmap.com/distance/route/json
?alternatives=true
&destination=49.31344%2C4.15293
&details=full
&language=en
&method=distance
&mode=driving
&origin=49.31067%2C4.14525
&key=YOUR_PUBLIC_API_KEY
curl -L -X GET 'https://api.woosmap.com/distance/route/json?origin=49.31067%2C4.14525&destination=49.31344%2C4.15293&mode=driving&language=en&alternatives=true&method=distance&details=full&key=YOUR_PUBLIC_API_KEY' \
-H 'Referer: http://localhost'
var requestOptions = {
method: 'GET',
redirect: 'follow'
};
fetch("https://api.woosmap.com/distance/route/json?origin=49.31067%2C4.14525&destination=49.31344%2C4.15293&mode=driving&language=en&alternatives=true&method=distance&details=full&key=YOUR_PUBLIC_API_KEY", requestOptions)
.then(response => response.text())
.then(result => console.log(result))
.catch(error => console.log('error', error));
var axios = require('axios');
var config = {
method: 'get',
url: 'https://api.woosmap.com/distance/route/json?origin=49.31067%2C4.14525&destination=49.31344%2C4.15293&mode=driving&language=en&alternatives=true&method=distance&details=full&key=YOUR_PUBLIC_API_KEY',
headers: {
'Referer': 'http://localhost'
}
};
axios(config)
.then(function (response) {
console.log(JSON.stringify(response.data));
})
.catch(function (error) {
console.log(error);
});
import requests
url = "https://api.woosmap.com/distance/route/json?origin=49.31067%2C4.14525&destination=49.31344%2C4.15293&mode=driving&language=en&alternatives=true&method=distance&details=full&key=YOUR_PUBLIC_API_KEY"
payload={}
headers = {
'Referer': 'http://localhost'
}
response = requests.request("GET", url, headers=headers, data=payload)
print(response.text)
OkHttpClient client = new OkHttpClient().newBuilder()
.build();
MediaType mediaType = MediaType.parse("text/plain");
RequestBody body = RequestBody.create(mediaType, "");
Request request = new Request.Builder()
.url("https://api.woosmap.com/distance/route/json?origin=49.31067%2C4.14525&destination=49.31344%2C4.15293&mode=driving&language=en&alternatives=true&method=distance&details=full&key=YOUR_PUBLIC_API_KEY")
.method("GET", body)
.addHeader("Referer", "http://localhost")
.build();
Response response = client.newCall(request).execute();
require "uri"
require "net/http"
url = URI("https://api.woosmap.com/distance/route/json?origin=49.31067%2C4.14525&destination=49.31344%2C4.15293&mode=driving&language=en&alternatives=true&method=distance&details=full&key=YOUR_PUBLIC_API_KEY")
https = Net::HTTP.new(url.host, url.port)
https.use_ssl = true
request = Net::HTTP::Get.new(url)
request["Referer"] = "http://localhost"
response = https.request(request)
puts response.read_body
Response
Route provides a JSON response containing the following root elements:
status contains metadata on the request. See Status Codes below.
routes contains an array of route, which in turn each contain a overview_polyline, bounds, legs and summary element.
{
"status": "OK",
"routes":
[
{
"overview_polyline":
{
"points": "a_~kHgrhXu@yAe@y@c@q@e@q@c@o@e@m@y@eAa@g@a@c@Y[UUQQYUQOSOQKSKOKQISIWKSEUEMCQAa@CeA@[E}@EUAOEOGKKIOM[I]Ea@A[?QBIBU?WFWDOLUP[P]j@y@^g@`@i@NUNONMJKJIFELCJBJAHGFIDMBSASBKDILURa@LWt@eAHQ",
},
"bounds":
{
"northeast": { "lat": 49.315678, "lng": 4.15292 },
"southwest": { "lat": 49.31073, "lng": 4.145162 },
},
"notice": "",
"legs":
[
{
"distance": { "text": "1 km", "value": 1038 },
"duration": { "text": "1 min", "value": 75 },
"start_location": { "lat": 49.31067, "lng": 4.14525 },
"end_location": { "lat": 49.31344, "lng": 4.15293 },
"start_waypoint": 0,
"end_waypoint": 1,
"end_address": "D 30",
"start_address": "D 151",
"steps":
[
{
"distance": "676 m",
"duration": "1 min",
"polyline": "a_~kHgrhXu@yAe@y@c@q@e@q@c@o@e@m@y@eAa@g@a@c@Y[UUQQYUQOSOQKSKOKQISIWKSEUEMCQAa@CeA@[E}@EUAOEOGKKIOM[I]Ea@A[?Q",
"start_location": { "lat": 49.31073, "lng": 4.145163 },
"end_location": { "lat": 49.315679, "lng": 4.149621 },
"travel_mode": "DRIVING",
"instructions":
{
"action": 2,
"summary": "Drive northeast on D 151.",
"verbal_succint": "Drive northeast. Then Enter the roundabout and take the 2nd exit onto D 30.",
"verbal_before": "Drive northeast on D 151. Then Enter the roundabout and take the 2nd exit onto D 30.",
"verbal_after": "Continue for 700 meters.",
},
},
{
"distance": "22 m",
"duration": "1 min",
"polyline": "}}~kHcniXBIBU?W",
"start_location": { "lat": 49.315679, "lng": 4.149621 },
"end_location": { "lat": 49.31563, "lng": 4.149905 },
"travel_mode": "DRIVING",
"instructions":
{
"action": 26,
"summary": "Enter the roundabout and take the 2nd exit onto D 30.",
"verbal_alert": "Enter the roundabout and take the 2nd exit onto D 30.",
"verbal_succint": "Enter the roundabout and take the 2nd exit.",
"verbal_before": "Enter the roundabout and take the 2nd exit onto D 30.",
},
},
{
"distance": "198 m",
"duration": "1 min",
"polyline": "u}~kH{oiXFWDOLUP[P]j@y@^g@`@i@NUNONMJKJIFELC",
"start_location": { "lat": 49.31563, "lng": 4.149905 },
"end_location": { "lat": 49.314292, "lng": 4.151623 },
"travel_mode": "DRIVING",
"instructions":
{
"action": 27,
"summary": "Exit the roundabout onto D 30.",
"verbal_succint": "Exit the roundabout.",
"verbal_before": "Exit the roundabout onto D 30.",
"verbal_after": "Continue for 200 meters.",
},
},
{
"distance": "46 m",
"duration": "1 min",
"polyline": "iu~kHsziXJBJAHGFIDMBSAS",
"start_location": { "lat": 49.314292, "lng": 4.151623 },
"end_location": { "lat": 49.314041, "lng": 4.151976 },
"travel_mode": "DRIVING",
"instructions":
{
"action": 26,
"summary": "Enter the roundabout and take the 1st exit onto D 30.",
"verbal_alert": "Enter the roundabout and take the 1st exit onto D 30.",
"verbal_succint": "Enter the roundabout and take the 1st exit.",
"verbal_before": "Enter the roundabout and take the 1st exit onto D 30.",
},
},
{
"distance": "96 m",
"duration": "1 min",
"polyline": "ws~kHy|iXBKDILURa@LWt@eAHQ",
"start_location": { "lat": 49.314041, "lng": 4.151976 },
"end_location": { "lat": 49.313434, "lng": 4.152921 },
"travel_mode": "DRIVING",
"instructions":
{
"action": 27,
"summary": "Exit the roundabout onto D 30.",
"verbal_succint": "Exit the roundabout. Then, in 100 meters, You will arrive at your destination.",
"verbal_before": "Exit the roundabout onto D 30. Then, in 100 meters, You will arrive at your destination.",
"verbal_after": "Continue for 100 meters.",
},
},
{
"distance": "1 m",
"duration": "1 min",
"polyline": "}o~kHwbjX",
"start_location": { "lat": 49.313434, "lng": 4.152921 },
"end_location": { "lat": 49.313434, "lng": 4.152921 },
"travel_mode": "DRIVING",
"instructions":
{
"action": 4,
"summary": "You have arrived at your destination.",
"verbal_alert": "You will arrive at your destination.",
"verbal_before": "You have arrived at your destination.",
},
},
],
},
],
},
],
}
Status Codes
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, …).
BACKEND_ERROR indicates a Distance API request could not be processed due to a server error. This may indicate that the origin and/or destination of this pairing could not be matched to the network, or that no route could be found that respects the avoid option. The request may or may not succeed if you try again.
MAX_ROUTE_LENGTH_EXCEEDED indicates that the origin and destination are too far away from each other.
OVER_QUERY_LIMIT (associated to a 429 status code) indicates that the number of queries per second (QPS) exceeds the usage limits.
Routes
Each routes contains the following fields:
overview_polyline: the polyline of the route (encoding with the poyline algorithm
bounds: the bounding box of the route
notice: some noticeable information about the route (for example : notice:Has highway segments)
legs: information about route between waypoints
notice field does not provide has toll segments information if traffic awareness parameters are part of the request.
Legs
Each legs contains the following fields:
distance: the distance of the leg in meters (value) and as text (text string generation will use the units parameter provided in the request to provide result accordingly).
duration: the duration of the leg in seconds (value) and as text
start_location: the starting location of the leg (it could be different from the given waypoint if there is no road close to it)
end_location: the ending location of the leg (it could be different from the given waypoint if there is no road close to it)
start_waypoint: the index of the waypoint where the leg starts from (different from the given order in case of reordering)
end_waypoint: the index of the waypoint where the leg ends at (different from the given order in case of reordering)
start_address: the starting address of the leg
end_address: the ending address of the leg
steps: list of steps constituting the leg. Steps are returned when the details parameter is specified. A step is the most atomic unit of a route, containing a single step describing a specific, single instruction on the journey. The step not only describes the instruction but also contains distance and duration information relating to how this step relates to the following step.
To obtain the total distance and duration for a route with multiple legs, you need to sum every legs values. Keep in mind that distance values are provided in meters whatever the units parameter provided in the request.
Steps
No steps included in responses to route with traffic awareness requests.
Each steps contains the following fields:
distance: the distance as text covered by this step until the next step (text string generation will use the units parameter provided in the request to provide result accordingly).
duration: the typical time as text required to perform the step, until the next step
polyline: the polyline representation of the step (encoding with the poyline algorithm
start_location: the location of the starting point of this step
end_location: the location of the last point of this step
travel_mode: the type of travel mode used
instructions: formatted instructions for this step
Instructions
No instructions included in responses to route with traffic awareness requests.
Each instructions contains the following fields:
action: the action to take for the current step (turn left, merge, straight, etc.). See below for a list.
summary: Written maneuver instruction
verbal_succint: text suitable for use as a verbal alert in a navigation application
verbal_before: text suitable for use as a verbal message immediately prior to the maneuver transition
verbal_after: text suitable for use as a verbal message immediately after the maneuver transition
For action, the allowed values include:
0: none
1: start
2: start right
3: start left
4: destination
5: destination right
6: destination left
7: becomes
8: continue
9: slight right
10: right
11: sharp right
12: uturn right
13: uturn left
14: sharp left
15: left
16: slight left
17: ramp straight
18: ramp right
19: ramp left
20: exit right
21: exit left
22: stay straight
23: stay right
24: stay left
25: merge
26: roundabout enter
27: roundabout exit
28: ferry enter
29: ferry exit
30: transit
31: transit transfer
32: transit remain on
33: transit connection start
34: transit connection transfer
35: transit connection destination
36: post transit connection destination
37: merge right
38: merge left
Route endpoint server side
As for other Woosmap APIs, if you plan to use the Route endpoint of Distance API sever side you must use a private_key in your requests.
.../distance/route/json?origin=48.836,2.237&destination=48.709,2.403&private_key=[Private APIKey]&mode=driving&language=en&units=metrics
Usage limits
The following usage limits are in place for the Route endpoint of Distance API:
- Maximum 25 waypoints per request.
- Maximum of 10 queries per second (QPS) per Project (so possibly the sum of client-side and server-side queries)
- Max distance between origin and destination should not exceed 500km.
Example
Here is a sample of a Distance API call using Javascript. It combines calls to Autocomplete endpoint to get suggestions while typing, a call to Geocode endpoint when clicking a suggestion and a call to Route endpoint using previous call’s result. It queries Route endpoint to get a distance, a duration and a path (as a polyline) of the better route between origin, destination and possible waypoints.
