Route endpoint [Deprecated]
How to get distance, time and polyline for a route between of origin and destination (including traffic).
- Overview
- Required parameters
- Optional Parameters
- Response
- Traffic Route API server side
- Usage limits
- Example
Traffic API is deprecated as of March 31, 2023, and will be turned off on September 31, 2023. Use Distance API with proper parameters instead.
Overview
The Woosmap Traffic Route endpoint is a service that provides route distances, durations with traffic and path between an origin and a destination, supporting waypoints in between. Compared to the Woosmap Route API, this Traffic API uses traffic information when returning duration times. The service provides all the information needed to evaluate an itinerary and display it on a map. Duration values are provided in case traffic makes a longer route faster.
Requests should be build as follow:
https://api.woosmap.com/traffic/route/?parameters
Required parameters
Certain parameters are required to initiate a Traffic Route request. The request is expected to be a GET request which sends json information or a GET request with parameters.
GET example:
GET https://api.woosmap.com/traffic/route/json?key=XXX&origin=44.404027,8.945534&destination=41.902687,12.496313
origin
The starting point for the route. It should be supplied in the form of latitude/longitude coordinates. Latitude and longitude should be coma (‘,’) separated. 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. Latitude and longitude should be coma (‘,’) separated. Ensure that no space exists between the latitude and longitude values.
key or private_key
Your project’s API key. This key identifies your Woosmap Project for security purposes and 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
routing
Specifies what to base the cost calculation on. Valid values are fastest and shortest.
Default Value = fastest
Fastest will include traffic and route you based on the smallest travel time.
Shortest will optimise based on travel distance.
language
The language code (ISO 639-1), indicating in which language the results should be returned, if possible. If language is not supplied, the Traffic 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 alternatives route should be returned. Valid values are true, false, 1...6 (default is false)
waypoints
A list of points by which the route should pass. (route response is divided into legs, one leg corresponding at a route between two waypoints).
Waypoints should be separated by | character. (example : waypoints=48.850077, 3.311124|48.850077, 3.411124)
departure_time
The timestamp to base the calculation on. Valid values are timestamp or now.
arrival_time
The timestamp to base the calculation on. Valid values are timestamp.
One of departure time or arrival time is mandatory, but do not give both.
avoid
The list of nodes that you want to avoid. Valid values are tolls.
Response
Traffic Distance 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.
{
"routes":
[
{
"legs":
[
{
"distance": { "value": 1068.2679083828243, "text": "1.1 km" },
"duration_with_traffic": { "value": 96, "text": "2 mins" },
"duration_without_traffic": { "value": 86, "text": "1 min" },
"start_location": { "lat": 49.310753, "lng": 4.1451221 },
"end_location": { "lat": 49.313436, "lng": 4.1529229 },
},
],
"overview_polyline":
{
"points": "e_~kH_rhXkBcDsAwBeAaB]c@a@g@c@g@c@a@[[a@_@YS[Ui@Y]O]K_@Gc@Gi@AcBCg@?_@ESCOMMMMUKYI]Ow@FIFMBI@G@O?IAMCMCKjCsDNShBaCDFDDDBF@F?FABADADIBC@GBM@M?KAKCKCG|@kA`AsA",
},
"summary": "route_0",
"bounds":
{
"northeast": { "lat": 49.31575, "lng": 4.152923 },
"southwest": { "lat": 49.310753, "lng": 4.145122 },
},
},
],
"status": "OK",
}
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 Traffic Route service (e.g. wrong API Key, wrong/no referer, …).
UNKNOWN_ERROR indicates a Traffic Route request could not be processed due to a server error. The request may succeed if you try again.
Routes
Each route contains the following fields:
overview_polyline: The polyline of the route (encoding with the poyline5 algorithm .
bounds: The bounding box of the route.
summary: A short name for the route.
legs: Information about route between waypoints.
Legs
Each leg contains the following fields:
distance: the distance of the leg.
duration_with_traffic: the duration of the leg, considering the traffic.
duration_without_traffic: the duration of the leg, considering no traffic.
start_location: the starting location of the leg (it could be different from the given waypoint if there is no road on for it)
end_location: the ending location of the leg (it could be different from the given waypoint if there is no road on for it)
Traffic Route API server side
As for other Woosmap APIs, if you plan to use Traffic Route endpoint server side you must use a private_key in your requests.
.../traffic/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 Traffic API:
- Maximum of 10 queries per second (QPS) per Project (so possibly the sum of client-side and server-side queries)
Example
Here is a sample of a Traffic 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.
