Distance Matrix endpoint

How to compute travel distance and time (including traffic) for a matrix of origins and destinations.

  1. Overview
  2. Required parameters
  3. Optional Parameters
  4. Response
  5. Usage limits

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

Overview

The Woosmap Traffic Distance Matrix endpoint is a service that provides travel distances and durations with traffic for matrices of origins and destinations. Compared to the Woosmap Distance API, Traffic API uses traffic information when returning duration times. The service returns information consisting of rows containing distance and duration values for each pair of start and end points. The returned distances are designed to be used to find and sort multiple assets by road distance. Duration values are provided in case traffic makes a longer route faster.

Requests should be build as follow:

https://api.woosmap.com/traffic/distancematrix/json?parameters

Required parameters

Certain parameters are required to initiate a Traffic Distance Matrix request. The request is expected to be a POST request which sends json information or a GET request with parameters.
POST example content type application/json must be set in the headers:

POST https://api.woosmap.com/traffic/distancematrix/json?key=XXXXXX
Content-Type: application/json
Body:
{
    "origins": "40.53787,15.30896|40.53787,15.20896|40.53787,15.10896",
    "destinations": "42.53787,13.40896|42.63787,13.40896|32.73787,13.40896",
    "units": "imperial",
    "language": "en"
}

GET example:

GET https://api.woosmap.com/traffic/distancematrix/json?key=XXX&origins=44.404027,8.945534|44.493722,11.343313&destinations=41.902687,12.496313|43.769755,11.256058

For POST requests, the body/parameters must contain the following fields:

origins

The starting points for calculating travel distances/durations.

"origins": "44.404027,8.945534|44.493722,11.343313"

destinations

One or more locations to use as the finishing point for calculating travel distances/durations.

"destinations": "42.53787,13.40896|42.63787,13.40896|32.73787,13.40896"

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

routing

Specifies what to base the cost calculation on. Valid values are fastest and balanced.
Default Value = fastest

Fastest will include traffic and route you based on the smallest travel time.
Balanced will optimise based on travel time and distance.

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

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

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 Distance Matrix service will use the default language “en”.

Response

Traffic Distance Matrix endpoint provides a JSON response containing the following root elements:
status contains metadata on the request. See Status Codes below.
rows contains an array of elements, which in turn each contains an array of results which contain status,distance and duration_with_traffic elements.

{
  "rows": [
    {
      "elements": [
        {
          "status": "OK", 
          "duration_with_traffic": {"value": 20816, "text": "5 hours 47 minutes"}, 
          "distance": {"value": 504057, "text": "504 km"}
        }, 
        {
          "status": "OK",  
          "duration_with_traffic": {"value": 10847, "text": "3 hours 1 minute"}, 
          "distance": {"value": 249421, "text": "249 km"}
        },
        {
          "status": "FAILED"
        }
      ]
    }
  ],
  "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 Distance Matrix service (e.g. wrong API Key, wrong/no referer, …).
UNKNOWN_ERROR indicates a Traffic Distance Matrix request could not be processed due to a server error. The request may succeed if you try again.

Elements

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, expressed in minutes (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.
FAILED: indicates that the origin and/or destination of this pairing could not be matched to the network.

Usage limits

The Traffic Distance Matrix service is limited by the number of origins and destinations it can take.
With only 1 destination it can take 100 origins: 100*1
With 15 or less origins it can take up to 100 destinations: 15*100

The following usage limits are also in place for the Traffic API:

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