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

Matrix Routing

 

Service version: 1
Last edit: 2019.02.18

On this page

Purpose

The Matrix Routing service enables the calculation of 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.

Example of a matrix

For origins: A, B, and destinations: X, Y, Z: the route summaries will be provided in a matrix Response in the following order:

Origin Destination
A X
A Y
A Z
B X
B Y
B Z

Asynchronous and Synchronous Matrix processing

You can call the Matrix Routing APIs to run either asynchronously or synchronously.

▲ Return to top

Asynchronous API overview

The Asynchronous API is appropriate for processing big volumes of relatively complex routing requests.

  • It allows the retrieval of results in a separate call (multiple downloads are possible).
  • The Asynchronous API is optimized for reliability and is not expected to run into a timeout.
  • The maximum size of a matrix for this API is 700 (the number of origins multiplied by the number of destinations), so examples of matrix dimensions are: 5x10, 10x10, 28x25 (it does not need to be square).

Data retention period notice

Please be aware that matrices processed by the Asynchronous API are available for download for 14 days, after which a Request for results download will return a HTTP 404 (Not Found) Response.

Sequence of Asynchronous client actions

  1. A client sends a Request to the Asynchronous Matrix Submission endpoint.
  2. The server will respond with one of:
  3. After getting a HTTP 303 Response, the client should follow the redirect to the Asynchronous Matrix Download endpoint which is a blocking long poll Request.
  4. The client waits for a matrix Response. Possible scenarios are:
    • The matrix Response is calculated before timeout.
      • The client receives HTTP 200.
      • The matrix Response is ready and it is being returned to the client.
    • The matrix Response is not ready before timeout.
      • The client receives HTTP 202.
      • The matrix Request is accepted for processing.
      • The client downloads the matrix results from the URL specified by the Location header (see point 3).

▲ Return to top

Synchronous API overview

The Synchronous API is recommended for lightweight routing requests with quickly-expiring results (e.g., due to changing traffic conditions).

  • In such a case, when the service receives a Request, it will respond as soon as the route summaries of the matrix are calculated, and there will be no possibility to retrieve the results later on.
  • The Synchronous API will return a timeout error if the Request takes longer than 60 seconds.
  • The maximum size of a matrix is limited to 100 for this API (the number of origins multiplied by the number of destinations), so examples of matrix dimensions are: 5x10, 10x10, 20x5 (it does not need to be square).

Sequence of Synchronous Matrix API client actions

  1. A client sends a Request to the Synchronous Matrix endpoint.
  2. The server will respond with one of the following:
    • A HTTP 200 Matrix processing result. The calculation is finished before timeout and the client downloads the results straight away.
    • A HTTP 408 Request timeout error. If the Request takes longer than 60 seconds and cannot be finished in this timeframe.
    • Another HTTP error. See the Synchronous Matrix HTTP status codes section.

▲ Return to top

You are here