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 Route API server side
  6. Usage limits
  7. Example

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 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": 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 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:

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.

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