Route endpoint

How to get distance, time and polyline for a route between of origin and destination (including traffic).

  1. Overview
  2. Required parameters
  3. Optional Parameters
  4. Response
  5. Traffic Distance Route API server side
  6. Usage limits

Route with traffic endpoint is in Early Access stage. See more details on Early Access here.

Overview

The Woosmap Traffic Route endpoint is a service that provides route distances, durations with traffic and path between of origin and destination (supporting waypoints). 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 supply 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 supply in the form of latitude/longitude coordinates. 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

mode

Specifies the mode of transport to use when calculating distance. Valid values are driving and truck.
Default value = driving

language

The language code (ISO 639-1), 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 |

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.

Departure time or arrival time is mandatory.

avoid

The list of nodes that you want to avoid. Valid values are ferries, tolls and highways.

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": 183086.63764032678,
            "text": "183 km"
          },
          "duration_with_traffic": {
            "value": 7739,
            "text": "2 hours 9 mins"
          },
          "duration_without_traffic": {
            "value": 7259,
            "text": "2 hours 1 mins"
          },
          "start_location": {
            "lat": 52.5309837,
            "lng": 13.384567
          },
          "end_location": {
            "lat": 53.5327365,
            "lng": 13.3784361
          }
        }
      ],
      "overview_polyline": {
        "points": "s}[email protected]@G][email protected]"
      },
      "summary": "road_0",
      "bounds": {
        "northeast": {
          "lat": 53.58457,
          "lng": 13.41868
        },
        "southwest": {
          "lat": 52.530984,
          "lng": 13.384567
        }
      }
    }
  ],
  "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 elements contains the following fields:
status: See Elements 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_with_traffic: The total duration to travel this route with traffic, expressed in minutes (value) and as text. The textual value gives a structured string for duration in the specified language (if available). duration_without_traffic: The total duration to travel this route without traffic, expressed in minutes (value) and as text. The textual value gives a structured string for duration in the specified language (if available).

Routes

Each routes 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 legs contains the following fields:
distance: the distance of the leg.
duration: the duration of the leg.
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 Distance Route API server side

As for other Woosmap APIs, if you plan to use Traffic Route endpoint sever 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:

Was this article helpful?
Have more questions? Submit a request