Products
Distance Api
Distance Matrix endpoint

April 22, 2024

Distance Matrix endpoint

How to compute travel distance and time for a matrix of origins and destinations.

Required parameters
Optional parameters
Traffic awareness parameter (optional)
Distance Matrix example
Response
Distance API server side
Usage limits
Example
Support of POST method

Get distances and durations for a matrix of origins and destinations, based on the recommended route between start and end points for a specified travel mode. The API returns information consisting of rows containing distance and duration values for each pair of start and end point. The returned distances are designed to be used to find and sort multiple assets by road distance. Duration values are either based on average speed, or with traffic awareness according to request parameters.

Requests should be build as follow:

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

Required parameters

Some parameters are required to initiate a Distance Matrix API request. As it is standard in URLs, all parameters are separated using the ampersand (&) character. The list of parameters and their possible values are enumerated below.

        https://api.woosmap.com/distance/distancematrix/json?origins=48.836,2.237&destinations=48.709,2.403|48.768,2.338|enc:gbxhHoo}M:|49.987,2.223&key={PUBLIC_API_KEY}

origins

The starting point for calculating travel distance. You can supply one or more locations separated by the pipe character (|), in the form of latitude/longitude coordinates. They are used unchanged to calculate distance. Ensure that no space exists between the latitude and longitude values.

destinations

One or more locations to use as the finishing point for calculating travel distance. The options for the destinations parameter are the same as for the origins parameter, described above.

In order to reduce URL size, encoded polylines are also supported for origins and destination using enc:encoded-polyline:

key

Your project’s API key. This key identifies your Woosmap Project for purposes of 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

        .../distance/distancematrix/json?origins=48.836,2.237&destinations=48.709,2.403|48.841,2.328|48.823,2.326|48.768,2.338|49.123,2.524|48.789,2.456|49.987,2.223&key=[APIKey]&mode=driving&language=en&units=metrics

mode

Specifies the mode of transport to use when calculating distance. Valid values are driving, cycling, walking. (if not specified default is driving)

language

The language code, 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 |

elements

Specifies element values that will be part of the API response (distance and/or duration). Valid values are distance, duration, duration_distance (if not specified default is distance)

method

Specifies the method to compute the route between elements:

time: fastest route (default)
distance: shortest route

avoid

Specifies features and/or zones to avoid when computing a route.

A feature to avoid is given by its name, features currently supported are:
- tolls: Find a route that does not pass through toll segments.
- highways: Find a route that does not pass through highway segments.
- ferries: Find a route that does not pass through ferry segments.

Note that sometimes ferries, highways or toll are required to complete a route so setting those parameters are not guaranteed to avoid them entirely.

A zone to avoid is given as a polygon, formed by a list of coordinates:
- You need to give at least 3 coordinates for each zone
- Each coordinate is separated by a semi-column (;)
- A coordinate is given in the form of a couple of latitude,longitude.
You can mix features and zones, using the pipe (|) separator
Limitation : the total perimeter of each zone can not exceed 10km.

example : avoid=tolls|42.2345,2.4536;42.35664,2.66736;43.34534,3.25534|42.5543,2.2565;42.67764,2.5625;43.6736,3.5545

Traffic awareness parameter (optional)

To get matrix calculation taking into account live traffic conditions, historical traffic patterns, or time-dependent restrictions, you can either use the departure_time.

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

Distance Matrix example

The following example requests the distance matrix between a pair of origins to one destination, using the distance method and retrieving the duration_distance in response with imperial unit system. Request is done with the POST method:

Distance Matrix call

URL

cURL

NodeJS

Python

Java

Ruby

            https://api.woosmap.com/distance/distancematrix/json
  ?private_key=YOUR_PRIVATE_API_KEY
    

            curl -L -X POST 'https://api.woosmap.com/distance/distancematrix/json?private_key=YOUR_PRIVATE_API_KEY' \
-H 'content-type: application/json' \
--data-raw '{
  "origins": "48.73534,2.368308|48.73534,2.368308",
  "destinations": "48.83534,2.368308",
  "units": "imperial",
  "elements": "duration_distance",
  "method": "distance",
  "departure_time": "now"
}'

    

            var axios = require('axios');
var data = JSON.stringify({
  "origins": "48.73534,2.368308|48.73534,2.368308",
  "destinations": "48.83534,2.368308",
  "units": "imperial",
  "elements": "duration_distance",
  "method": "distance",
  "departure_time": "now"
});

var config = {
  method: 'post',
  url: 'https://api.woosmap.com/distance/distancematrix/json?private_key=YOUR_PRIVATE_API_KEY',
  headers: { 
    'content-type': 'application/json'
  },
  data : data
};

axios(config)
.then(function (response) {
  console.log(JSON.stringify(response.data));
})
.catch(function (error) {
  console.log(error);
});


    

            import requests
import json

url = "https://api.woosmap.com/distance/distancematrix/json?private_key=YOUR_PRIVATE_API_KEY"

payload = json.dumps({
    "origins": "48.73534,2.368308|48.73534,2.368308",
    "destinations": "48.83534,2.368308",
    "units": "imperial",
    "elements": "duration_distance",
    "method": "distance",
    "departure_time": "now"
})
headers = {
    'content-type': 'application/json'
}

response = requests.request("POST", url, headers=headers, data=payload)

print(response.text)


    

            OkHttpClient client = new OkHttpClient().newBuilder()
  .build();
MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\n  \"origins\": \"48.73534,2.368308|48.73534,2.368308\",\n  \"destinations\": \"48.83534,2.368308\",\n  \"units\": \"imperial\",\n  \"elements\": \"duration_distance\",\n  \"method\": \"distance\",\n  \"departure_time\": \"now\"\n}");
Request request = new Request.Builder()
  .url("https://api.woosmap.com/distance/distancematrix/json?private_key=YOUR_PRIVATE_API_KEY")
  .method("POST", body)
  .addHeader("content-type", "application/json")
  .build();
Response response = client.newCall(request).execute();

    

            require "uri"
require "json"
require "net/http"

url = URI("https://api.woosmap.com/distance/distancematrix/json?private_key=YOUR_PRIVATE_API_KEY")

https = Net::HTTP.new(url.host, url.port)
https.use_ssl = true

request = Net::HTTP::Post.new(url)
request["content-type"] = "application/json"
request.body = JSON.dump({
  "origins": "48.73534,2.368308|48.73534,2.368308",
  "destinations": "48.83534,2.368308",
  "units": "imperial",
  "elements": "duration_distance",
  "method": "distance",
  "departure_time": "now"
})

response = https.request(request)
puts response.read_body


    

Response

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

            {
  "status": "OK",
  "rows":
    [
      {
        "elements":
          [
            {
              "status": "OK",
              "duration": { "value": 1248, "text": "21 mins" },
              "distance": { "value": 12221, "text": "7.6 miles" },
            },
          ],
      },
      {
        "elements":
          [
            {
              "status": "OK",
              "duration": { "value": 1248, "text": "21 mins" },
              "distance": { "value": 12221, "text": "7.6 miles" },
            },
          ],
      },
    ],
}

    

Status Codes

OK indicates the response contains a valid result.
INVALID_REQUEST indicates that the provided request was invalid (e.g. wrong URL syntax).
MAX_ELEMENTS_EXCEEDED indicates that the product of origins and destinations exceeds the per-query limit (fixed at 200 elts/q).
MAX_ROUTE_LENGTH_EXCEEDED indicates that at least one of requested route is too long and the matrix cannot be processed (>500km).
REQUEST_DENIED indicates that the service denied use of the Distance API service (e.g. wrong API Key, wrong/no referer, …). BACKEND_ERROR indicates a Distance API request could not be processed due to a server error. This may indicate that some origin and/or destination of this matrix could not be matched to the network, or that no route could be found that respects the avoid option. OVER_QUERY_LIMIT (associated to a 429 status code) indicates that the number of queries per second (QPS) or the number of elements per second (EPS) exceed the usage limits

Elements

Each element contains the following fields:
status: See 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: The total duration to travel this route, expressed in seconds (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.
NOT_FOUND indicates that the origin and/or destination of this pairing could not be matched to the network.
ZERO_RESULTS indicates no route could be found between the origin and destination.

Distance API server side

As for other Woosmap APIs, if you plan to use Distance API sever side you must use a private_key in your requests.

        .../distance/distancematrix/json?origins=48.836,2.237&destinations=48.709,2.403|48.841,2.328|48.823,2.326|48.768,2.338|49.123,2.524|48.789,2.456|49.987,2.223&private_key=[Private APIKey]&mode=driving&language=en&units=metrics

Usage limits

The following usage limits are in place for the Distance API:

Maximum 200 elements per client-side or server side request.
Maximum of 10 queries per second (QPS) per Project (so possibly the sum of client-side and server-side queries)
1000 elements per second (EPS) per Project, calculated as the sum of queries for one Woosmap Project (so possibly the sum of client-side and server-side queries).

Example

Here is a sample of a Distance API call using Javascript. It queries Distance Matrix through woosmap.map.DistanceService 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.

Distance Matrix POST call

URL

cURL

NodeJS

Python

Java

Ruby

            https://api.woosmap.com/distance/distancematrix/json
  ?private_key=YOUR_PRIVATE_API_KEY
    

            curl -L -X POST 'https://api.woosmap.com/distance/distancematrix/json?private_key=YOUR_PRIVATE_API_KEY' \
-H 'content-type: application/json' \
--data-raw '{
  "origins": "48.73534,2.368308|48.73534,2.368308",
  "destinations": "48.83534,2.368308",
  "units": "imperial",
  "elements": "duration_distance",
  "method": "distance",
  "departure_time": "now"
}'

    

            var axios = require('axios');
var data = JSON.stringify({
  "origins": "48.73534,2.368308|48.73534,2.368308",
  "destinations": "48.83534,2.368308",
  "units": "imperial",
  "elements": "duration_distance",
  "method": "distance",
  "departure_time": "now"
});

var config = {
  method: 'post',
  url: 'https://api.woosmap.com/distance/distancematrix/json?private_key=YOUR_PRIVATE_API_KEY',
  headers: { 
    'content-type': 'application/json'
  },
  data : data
};

axios(config)
.then(function (response) {
  console.log(JSON.stringify(response.data));
})
.catch(function (error) {
  console.log(error);
});


    

            import requests
import json

url = "https://api.woosmap.com/distance/distancematrix/json?private_key=YOUR_PRIVATE_API_KEY"

payload = json.dumps({
    "origins": "48.73534,2.368308|48.73534,2.368308",
    "destinations": "48.83534,2.368308",
    "units": "imperial",
    "elements": "duration_distance",
    "method": "distance",
    "departure_time": "now"
})
headers = {
    'content-type': 'application/json'
}

response = requests.request("POST", url, headers=headers, data=payload)

print(response.text)


    

            OkHttpClient client = new OkHttpClient().newBuilder()
  .build();
MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\n  \"origins\": \"48.73534,2.368308|48.73534,2.368308\",\n  \"destinations\": \"48.83534,2.368308\",\n  \"units\": \"imperial\",\n  \"elements\": \"duration_distance\",\n  \"method\": \"distance\",\n  \"departure_time\": \"now\"\n}");
Request request = new Request.Builder()
  .url("https://api.woosmap.com/distance/distancematrix/json?private_key=YOUR_PRIVATE_API_KEY")
  .method("POST", body)
  .addHeader("content-type", "application/json")
  .build();
Response response = client.newCall(request).execute();

    

            require "uri"
require "json"
require "net/http"

url = URI("https://api.woosmap.com/distance/distancematrix/json?private_key=YOUR_PRIVATE_API_KEY")

https = Net::HTTP.new(url.host, url.port)
https.use_ssl = true

request = Net::HTTP::Post.new(url)
request["content-type"] = "application/json"
request.body = JSON.dump({
  "origins": "48.73534,2.368308|48.73534,2.368308",
  "destinations": "48.83534,2.368308",
  "units": "imperial",
  "elements": "duration_distance",
  "method": "distance",
  "departure_time": "now"
})

response = https.request(request)
puts response.read_body


    

The API Key should still be pass as URL argument

‹ Get Started Route ›

Was this article helpful?

Have more questions? Submit a request