Calculate Matrix

POST

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

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.

Rate limit: 10 requests/1s GET and POST

Elements limit: 1000 elements/1s GET and POST

Rate limit with TRAFFIC: 10 requests/1s GET and POST

Elements limit with TRAFFIC: 1000 elements/1s GET and POST

Authorization

key

apiKey query

Public key of the project usually starts with woos-

private_key

apiKey query

Private key with or without write permission.

X-Api-Key

apiKey header

Private key with or without write permission.

Header Parameters

accept-language

object

Request Body

application/json

mode

string Defaults to driving

Specifies the mode of transport to use for the calculation.

Available options: driving, walking, cycling

method

string Defaults to time

Specifies how to compute the route between the start point and the end point:

• time: fastest route
• distance: shortest route

Available options: time, distance

units

string Defaults to metric

Specifies the unit system to use when displaying results.

Available options: metric, imperial

language

string Defaults to en

The language code, indicating in the language the response should be in.

If not defined the header Accept-Language of the request will be checked before defaulting to en.

Show 20 enum values Hide 20 enum values

en

fr

ca

da

de

es

et

fi

he

it

ja

nb

nl

pl

pt

ro

ru

sv

uk

zh

avoid

string

A list of features that you want to avoid. Valid values are tolls, highways, ferries or polygons coordinates whose vertex latlng are separated by a semicolon ;.

To add multiple features, separate them with the pipe | character.

origins

string required

The starting points. You can supply one or more locations, in the form of latitude,longitude coordinates, separated by the pipe character |. Ensure that no space exists between the latitude and longitude values.

In order to reduce URL size, encoded polylines are also supported using enc:<encoded-polyline>:

destinations

string required

The ending points. You can supply one or more locations, in the form of latitude,longitude coordinates, separated by the pipe character |. Ensure that no space exists between the latitude and longitude values.

In order to reduce URL size, encoded polylines are also supported using enc:<encoded-polyline>:

arrival_time

string

Specify your desired arrival time.

By using this parameter, Distance will calculate the duration with traffic. Valid values are a UNIX timestamp (e.g. 1600799173 for the date: 22/09/2020 20:26:13) or now.

Use either arrival_time or departure_time, not both.

departure_time

string

Specify your desired departure time.

By using this parameter, Distance will calculate the duration with traffic. Valid values are a UNIX timestamp (e.g. 1600799173 for the date: 22/09/2020 20:26:13) or now.

Use either arrival_time or departure_time, not both.

elements

string Defaults to distance

Specifies element values that will be part of the API response (distance and/or duration).

Available options: distance, duration, duration_distance

Example

Example

JSON

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

200 application/json

Successful Response

status

string Defaults to OK

The status of the response

• OK: The response contains a valid result.
• INVALID_REQUEST: The request could not be processed.
• MAX_ELEMENTS_EXCEEDED: The product of origins and destinations exceeds the per-query limit (fixed at 200 elts/query).
• MAX_ROUTE_LENGTH_EXCEEDED: One of requested routes is too long and the matrix/route cannot be processed (The limit is 500km).
• REQUEST_DENIED: The API key provided is invalid or does not allow access to this service etc..
• BACKEND_ERROR: The server encountered an unexpected error.
• OVER_QUERY_LIMIT: The request was denied due to the rate limit (see Usage Limits).
• ZERO_RESULTS: No route could be found between the origin and destination.

Show 8 enum values Hide 8 enum values

OK

INVALID_REQUEST

MAX_ELEMENTS_EXCEEDED

MAX_ROUTE_LENGTH_EXCEEDED

REQUEST_DENIED

BACKEND_ERROR

OVER_QUERY_LIMIT

ZERO_RESULTS

rows

object[] required

Contains an array of elements for each pair of origin and destination

Show 1 propertiesHide 1 properties

rows. elements

any[] required

An array of each route element.

Errors

401

Unable to locate credentials.

application/json

detail

string required

402

Out of free quota.

application/json

detail

string required

403

Credentials found, but not matching.

application/json

detail

string required

422

Validation Error

application/json

detail

object[]

Show 3 propertiesHide 3 properties

detail. loc

any[] required

detail. msg

string required

detail. type

string required

429

Rate limit reached

application/json

details

string required

cURL

JavaScript

Python

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

    

        const myHeaders = new Headers();
myHeaders.append("content-type", "application/json");

const raw = 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"
});

const requestOptions = {
  method: "POST",
  headers: myHeaders,
  body: raw,
  redirect: "follow"
};

fetch("https://api.woosmap.com/distance/distancematrix/json?private_key=YOUR_PRIVATE_API_KEY", requestOptions)
  .then((response) => response.text())
  .then((result) => console.log(result))
  .catch((error) => console.error(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)


    

200

        
{
  "status": "OK",
  "rows": [
    {
      "elements": [
        {
          "status": "OK",
          "duration": {
            "value": 2406,
            "text": "40 mins"
          },
          "distance": {
            "value": 12210,
            "text": "7.6 miles"
          }
        }
      ]
    },
    {
      "elements": [
        {
          "status": "OK",
          "duration": {
            "value": 2406,
            "text": "40 mins"
          },
          "distance": {
            "value": 12210,
            "text": "7.6 miles"
          }
        }
      ]
    }
  ]
}

    

Was this helpful?

Failed to send feedback. Please try again.

Thanks for your feedback!