Sorry, you need to enable JavaScript to visit this website.

Matrix Routing v2


Service version: 2
Last edit: 2021.09.07

Public Preview Notice

This API is in Public Preview. Go to the Public Preview - what is it? page to see what this means.

On this page


The Matrix Routing v2 API allows clients to calculate a matrix of route summaries for a set of routes defined with origin and destination locations.

  • For every given origin, this service calculates the cost of routing from that origin to every given destination.
  • The set of origins and the set of destinations can be thought of as the column and row headers of a table, while each cell in the table contains the costs of routing from the origin to the destination for that cell.

The following costs are computed for each route:

  • Travel times
  • Distances

Use the computed costs to determine which routes to calculate using the Routing API suite.

API overview

  • The Matrix Routing v2 API offers asynchronous endpoints suited for long-running calculations, as well as a synchronous endpoint for faster calculation of smaller matrices:
  • The maximum size of a matrix (the number of origins multiplied by the number of destinations) is:
    • 50625 for asynchronous version.
    • 2500 for synchronous version.
  • Additional matrix shape constraints apply, see the according endpoint documentation pages for details.
  • Routing options common for the whole matrix may be provided inside the request body.
  • The Matrix Routing v2 API supports only JSON format for request and response body.

Data retention period notice

The matrices processed by the asynchronous API are available for download for 14 days, after which a request for a result download will return an HTTP 404 (Not Found) response.

Sequence of client actions using asynchronous endpoints

  1. A client sends a request to the Asynchronous Matrix Submission endpoint.
  2. The server responds with an HTTP 202 response with a JSON body having a Submitted status and a generated Job ID.
  3. The client may send (multiple) requests to the Asynchronous Matrix Status endpoint, providing the previously acquired Job ID.
  4. The server will respond with an HTTP 200 response with a JSON body having a state equal to one of:
    • Submitted - request hasn't been validated yet.
    • Validated - request is validated and it's being processed.
    • Completed - request is processed and results are available for download.
    • Failed - processing of the given job could not be successfully completed.
  5. When the state is Completed, the client may call the Asynchronous Matrix Download endpoint to get the results.
  6. On a download request, the server will instantly start the download. If the results are not available (state is other than Completed), then the Download endpoint will return an HTTP 404 and there will be no long polling.

▲ Return to top