Distance Matrix endpoint

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

  1. Required parameters
  2. Optional parameters
  3. Distance Matrix API Response
  4. Distance API server side
  5. Usage limits
  6. Example
  7. 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 provided as complementary info.

Requests should be build as follow:


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.



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.


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:


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



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


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


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 |


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)


Specifies the method to compute the route between elements:


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

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

Distance Matrix API Response

Distance 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 contain a status, distance and duration element.

  "status": "OK",
  "rows": [
      "elements": [
          "status": "OK",
          "duration": {
            "value": 845,
            "text": "14 mins"
          "distance": {
            "value": 7553.0,
            "text": "7.6 km"
          "status": "OK",
          "duration": {
            "value": 1058,
            "text": "18 mins"
          "distance": {
            "value": 8978.0,
            "text": "9.0 km"

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, …).
UNKNOWN_ERROR indicates a Distance API request could not be processed due to a server error. The request may succeed if you try again.
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


Each elements 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:


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 pass 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