Distance Matrix endpoint [Deprecated]

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. Distance Matrix example
  5. Response
  6. Usage limits
  7. Example
  8. Support of POST method

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

        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.

JSON
        "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.

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

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.

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:

Parameter Description
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”.

Distance Matrix example

The following example requests the distance matrix with traffic between an origin to a pair of destinations, using the shortest routing method and specifying a departure_time now:

Traffic Distance Matrix call
        https://api.woosmap.com/traffic/distancematrix/json
  ?departure_time=now
  &destinations=48.709%2C2.303%7C48.768%2C2.338
  &language=en
  &origins=48.709%2C2.403
  &routing=shortest
  &key=YOUR_PUBLIC_API_KEY
    
        curl -L -X GET 'https://api.woosmap.com/traffic/distancematrix/json?origins=48.709%2C2.403&destinations=48.709%2C2.303%7C48.768%2C2.338&routing=shortest&language=en&departure_time=now&key=YOUR_PUBLIC_API_KEY' \
-H 'Referer: http://localhost'

    
        var requestOptions = {
  method: 'GET',
  redirect: 'follow'
};

fetch("https://api.woosmap.com/traffic/distancematrix/json?origins=48.709%2C2.403&destinations=48.709%2C2.303%7C48.768%2C2.338&routing=shortest&language=en&departure_time=now&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/traffic/distancematrix/json?origins=48.709%2C2.403&destinations=48.709%2C2.303%7C48.768%2C2.338&routing=shortest&language=en&departure_time=now&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/traffic/distancematrix/json?origins=48.709%2C2.403&destinations=48.709%2C2.303%7C48.768%2C2.338&routing=shortest&language=en&departure_time=now&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/traffic/distancematrix/json?origins=48.709%2C2.403&destinations=48.709%2C2.303%7C48.768%2C2.338&routing=shortest&language=en&departure_time=now&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/traffic/distancematrix/json?origins=48.709%2C2.403&destinations=48.709%2C2.303%7C48.768%2C2.338&routing=shortest&language=en&departure_time=now&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

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.

Traffic Distance Matrix Response
JSON
        {
  "rows":
    [
      {
        "elements":
          [
            {
              "status": "OK",
              "duration_with_traffic": { "value": 1186, "text": "20 mins" },
              "distance": { "value": 10577, "text": "10.6 km" },
            },
            {
              "status": "OK",
              "duration_with_traffic": { "value": 1154, "text": "19 mins" },
              "distance": { "value": 10198, "text": "10.2 km" },
            },
          ],
      },
    ],
  "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 (element).
With only 1 destination, it can take 100 origins: 100*1 = 100 elements
With 15 or fewer origins, number of elements cannot exceed 200 elements

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

Example

Here is a sample of a Distance API call using Javascript. It queries Distance Matrix endpoint to get distances and durations between couples of origins and destinations.

Support of POST method

If the URL size is too short for your origins and destinations, you could also request the server using POST method and passing arguments as json.

The API Key should still be passed as URL argument

        curl -X POST 'https://api.woosmap.com/distance/distancematrix/json?key={PUBLIC_API_KEY}' \
  -H 'content-Type: application/json' \
  -H 'referer: http://localhost' \
  -d '{"origins": "48.73534,2.368308|48.73534,2.368308",
    "destinations": "48.83534,2.368308",
    "units": "imperial",
    "elements": "duration_distance"
  }'

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