Source: https://developers.woosmap.com/products/distance-api/features/matrix/ > For clean Markdown of any page, append `.md` to the page URL. > For a complete documentation index, see https://developers.woosmap.com/llms.txt # Distance Matrix **Complete API Specification** : [Matrix Endpoint Reference](/api-reference/distance-api/get-distance-distancematrix-json/) ## 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. For larger matrices that exceed the synchronous API limits, consider using the [Async Matrix API](/products/distance-api/features/matrix_async), which processes calculations asynchronously and supports higher element counts per job. 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. ```http GET https://api.woosmap.com/distance/distancematrix/json POST https://api.woosmap.com/distance/distancematrix/json ``` When authenticating via query parameter, the `key` or `private_key` must appear in the URL even for POST requests β€” not in the request body. If you use the `X-Api-Key` header instead, no URL parameter is needed. ### 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. You can also use the `X-Api-Key` header for server-side or mobile authentication. ```shell # Client-side (query parameter) ?origins=51.6511,-0.1615&destinations=51.4855,-0.3179|51.5146,-0.0212&key=YOUR_PUBLIC_KEY # Server-side (query parameter) ?origins=51.6511,-0.1615&destinations=51.4855,-0.3179|51.5146,-0.0212&private_key=YOUR_PRIVATE_KEY # Server-side / Mobile (header) -H "X-Api-Key: YOUR_PRIVATE_KEY" ``` For complete authentication details and security best practices, see [API Keys Documentation](/api-reference/authentication/). ## 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](/products/localities/features/geocoding) to retrieve the coordinates of an address. In order to reduce URL size, [encoded polylines](https://developers.google.com/maps/documentation/utilities/polylinealgorithm) are also supported for origins and destination using `enc::` **`key`** or **`private_key`** - Your API authentication key. See [Authentication](#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](/products/distance-api/concepts/language-support/#language-support-in-matrix-api) **`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](/products/distance-api/guides/tuning-route-results/) ## Complete Parameter Reference For all available parameters and advanced options see: - [OpenAPI Specification](/api-reference/distance-api/get-distance-distancematrix-json/) - Complete technical reference ## Request Examples ### Basic Distance Matrix ```shell 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 ```shell 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 ```shell 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 ```shell 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](/api-reference/distance-api/get-distance-distancematrix-json/) for the possible values. - **rows** contains an array of `elements`, which in turn each contains a `status` along with possible`distance` 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 ```json { "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](/products/map-api/reference/1.4/#woosmap.map.DistanceService) to get distances and durations between couples of origins and destinations. https://demo.woosmap.com/js-samples/samples/distance-matrix-advanced/app/dist/ [](https://demo.woosmap.com/js-samples/samples/distance-matrix-advanced/highlight/highlight.html "Open in new tab with highlighted code") Try sample - [CodeSandbox](https://codesandbox.io/p/devbox/github/woosmap/js-samples/tree/master/dist/samples/distance-matrix-advanced/app?file=index.ts) - [JsFiddle](https://jsfiddle.net/gh/get/library/pure/woosmap/js-samples/tree/master/dist/samples/distance-matrix-advanced/jsfiddle) - [Clone on Github](https://github.com/Woosmap/js-samples/tree/sample/distance-matrix-advanced)