Distance Matrix

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

Complete API Specification: Matrix Endpoint Reference

What is the Matrix Endpoint?

The Woosmap Distance Matrix Endpoint is a key service within the Woosmap platform that efficiently calculates the travel distance and duration between numerous origins and destinations in a single request. It is designed to solve complex, multi-point routing problems by generating a grid (or matrix) of results, making it ideal for proximity analysis and optimization tasks.

What It Does

This service returns a matrix of distances and travel times between all specified origins and destinations, using the most optimized route for the chosen travel mode. This information is key to finding and sorting assets by road distance.
Duration values are either based on average speed, or with traffic awareness according to request parameters.

Key Characteristics

Its primary feature is calculating all possible pairings in a grid (matrix) between a list of origins (starting points) and a list of destinations (ending points). This avoids the need for numerous individual API calls.

When to Use This Endpoint

The Woosmap Distance Matrix Endpoint is the right tool to use whenever you need to calculate the travel distance and time between many locations simultaneously for comparison and analysis, rather than generating turn-by-turn directions for a single route.
It is ideal for scenarios where the primary goal is optimization, sorting, or multi-point analysis.

Travel time with traffic may require specific product activation.

The Distance Matrix is billed per origin-destination pair, rather than per API request.

API Endpoint (GET and POST)

This endpoint can be called with either a GET or POST method.

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

Even if you use the POST method the API Key should still be passed as URL query parameter.

Authentication

Authenticate using either a key (public API key for client-side requests) or private_key (for server-side requests). Public keys require domain/IP restrictions, while private keys should be kept secret and never exposed in client code.

        # Client-side
?origins=51.6511,-0.1615&destinations=51.4855,-0.3179|51.5146,-0.0212&key=YOUR_PUBLIC_KEY

# Server-side
?origins=51.6511,-0.1615&destinations=51.4855,-0.3179|51.5146,-0.0212&private_key=YOUR_PRIVATE_KEY

For complete authentication details and security best practices, see API Keys Documentation.

Request Parameters Overview

Required Parameters

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.

You can use Localities Geocoding to retrieve the coordinates of an address.

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

key or private_key - Your API authentication key. See Authentication above.

Key Optional Parameters

mode - Specifies the mode of transport to use when calculating distance. Valid values are driving, cycling, walking. (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”. Check Supported Languages

units - Specifies the unit system to use when expressing distance as text. Two different units supported metric, imperial. (default is metric)

elements - By default, only the distance calculated between points is returned. If you require times as well you must specify distance_duration and if you only want times duration. (default is distance)

method - Specifies the method to compute the route between elements:

time: fastest route (default)
distance: shortest route

avoid - departure-time - arrival-time - More details in the Tuning section

Complete Parameter Reference

For all available parameters and advanced options see:

OpenAPI Specification - Complete technical reference

Request Examples

Basic Distance Matrix

        curl "https://api.woosmap.com/distance/distancematrix/json?origins=48.865,2.347&destinations=48.820,1.910|48.667,3.143|49.180,-0.362&key=YOUR_KEY"

Distance and Duration Matrix

        curl "https://api.woosmap.com/distance/distancematrix/json?origins=48.865,2.347&destinations=48.820,1.910|48.667,3.143|49.180,-0.362&elements=duration_distance&key=YOUR_KEY"

Distance and Duration Matrix with traffic awareness

        curl "https://api.woosmap.com/distance/distancematrix/json?origins=48.865,2.347&destinations=48.820,1.910|48.667,3.143|49.180,-0.362&elements=duration_distance&departure_time=now&key=YOUR_KEY"

Distance and Duration Matrix by bike

        curl "https://api.woosmap.com/distance/distancematrix/json?origins=48.865,2.347&destinations=48.820,1.910|48.667,3.143|49.180,-0.362&mode=cycling&elements=duration_distance&key=YOUR_KEY"

Understanding the Response

Distance provides a JSON response containing the following root elements:

status contains metadata on the request. Check the OpenAPI Specification for the possible values.
rows contains an array of elements, which in turn each contains a status along with possibledistance and duration elements.

Elements

Whether Distance and Duration fields are returned depends on the value set for the elements parameter:

status: Could be OK NOT_FOUND ZERO_RESULTS ERROR
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.

Response Examples

            {
  "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" },
            },
          ],
      },
    ],
}

    

Usage Limits & Quotas

The following usage limits are in place for the Distance Matrix Endpoint:

Maximum 200 elements per 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).
Max distance between origins and destinations should not exceed 500km.

Working Code Examples

Here is a sample call using JavaScript. It queries Distance Matrix through woosmap.map.DistanceService to get distances and durations between couples of origins and destinations.

‹ Get Started Route ›