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

Asynchronous Matrix Download

 

Service version: 1
Last edit: 2019.09.24

On this page

Purpose

This endpoint fetches results of the Asynchronous Matrix processing.

  • It responds with a HTTP 200 and the matrix results assuming that the matrix Request processing has completed, or a HTTP 202 (Accepted) if the matrix is still being processed.
  • HTTP 202 (Accepted) will be obtained after 120 seconds, then the client should retry the Request by following the Location header.
  • A HTTP 200 Response does not indicate that every matrix cell succeeded, only that the matrix calculation was completed.
  • Detailed information about the success or failure of the individual calculations of the requested route summaries within the matrix is provided in the HTTP 200 Response.

Note: The matrix download GET Request is a blocking long poll request.

Request data

HTTPS method: GET

URL example

For ease of viewing and identification:

  • Required constants and parameters are shown in bold text.
  • Optional parameters are shown in plain text.
https://baseURL/routing/versionNumber/matrix/matrixId?key=*****

Example

https://api.tomtom.com/routing/1/matrix/matrixId?key=*****

HTTP Request headers

The following table describes HTTP Request headers of particular interest to Matrix Routing service clients.

Required headers
Note: There are no required headers in this endpoint.
Optional headers
Header Description
Accept-Encoding Should contain a list of encodings acceptable by the client. This is used to demand a compressed Response.
Value: gzip
Accept
string
Indicates the format of the download error Response (e.g., a matrix with the provided matrixId does not exist). For instance, if a client submitted a matrix with an output format set to json and would like to get the download error Response in the same format, the Accept header should be set to application/json. Otherwise the download error Response will have the default format which is xml.
Note: In case of a successful Response, the Accept header value will not affect the matrix Response format.
Values:

  • application/xml
  • application/json
Tracking-ID
string
Specifies an identifier for the Request.

  • It can be used to trace a call.
  • The value must match the regular expression '^[a-zA-Z0-9-]{1,100}$'.
  • An example of format that matches this regular expression is UUID: (e.g., 9ac68072-c7a4-11e8-a8d5-f2801f1b9fd1). For details check RFC 4122.
  • If specified, it is replicated in the Tracking-ID Response header.

Value: An identifier for the Request.

Request parameters

The following table describes the Request parameters.

  • Required parameters must be used or the call will fail.
  • Optional parameters may be used.
  • A parameter's data type is beneath its name.
Required parameters
Parameter Description
baseURL
string
Base URL for calling the API.
Value: api.tomtom.com
versionNumber
integer
The service version number.
Value: The current value is 1.
key
string
An API Key valid for the requested service.
Value: Your valid API Key.
matrixId
string
The unique id of the matrix Response, returned in a HTTP 303. See the other HTTP Location header of the Matrix Submission Response.
Value: The unique id of the Matrix Response.
Optional parameters
Note: There are no optional parameters in this endpoint.

▲ Return to top

Response data

HTTP Response codes

Code Meaning and Possible Causes
200 OK: The matrix calculation has completed. Results are streamed to the client.
202 Accepted: The Request has been accepted for processing, but the processing has not been completed. A Location header is added to the Response containing a link to retry later.
400 Bad Request: Missing required parameters, or parameters didn't pass validation.
403 Forbidden: The API Key is missing, inactive, invalid, not entitled to use the Matrix Routing API over QPS, or over QPD. Can also occur when using HTTP instead of HTTPS.
404 Not Found: The requested resource could not be found. For example, a matrix with a provided matrixId does not exist.
405 Method Not Allowed: The client used an HTTP method other than GET.
408 Request timeout.
414 Requested URI is too long.
500 An error occurred while processing the Request. Please try again later.
502 Internal network connectivity issue. Please try again later.
503 Service currently unavailable. Please try again later.
504 Internal network connectivity issue or a request that has taken too long to complete. Please try again later.
596 Service not found. Request contains an incorrect FQDN and/or path.

▲ Return to top

HTTP Response headers

The following table lists HTTP Response headers of particular interest to Routing service clients.

Header Description
Access-Control-Expose-Headers A comma separated list of HTTP header names that browsers are allowed to access.
Value: Content-Length
Access-Control-Allow-Origin A header instructing browsers to allow customer websites to contact the Matrix Routing service.
Value: *
Content-Encoding The Matrix Routing service applies gzip compression to the Responses if it is requested by the client with the Accept-Encoding header.
Value: gzip
Content-Type The format of the Response as chosen by the client (see the contentType Request parameter).
Values:

  • application/xml;charset=utf-8
  • application/json;charset=utf-8
Location Indicates the location where the matrix results can be downloaded. Available only if the response is HTTP 202.
Value: URI
Tracking-ID An identifier for the Request.

  • If the Tracking-ID header was specified, it is replicated in the Response.
  • Otherwise, it is generated automatically by the service.

Value: An identifier for the Request.

▲ Return to top

Successful Response examples

Click to expand/collapse the following examples

XML Response

<?xml version="1.0" encoding="UTF-8"?>
<matrixResponse xmlns="http://api.tomtom.com/matrix" formatVersion="0.0.1">
  <matrix>
    <row>
      <cell>
        <statusCode>200</statusCode>
        <response>
          <routeSummary>
            <lengthInMeters>543514</lengthInMeters>
            <travelTimeInSeconds>21506</travelTimeInSeconds>
            <trafficDelayInSeconds>46</trafficDelayInSeconds>
            <departureTime>2018-08-10T10:17:49+02:00</departureTime>
            <arrivalTime>2018-08-10T16:16:14+02:00</arrivalTime>
            <noTrafficTravelTimeInSeconds>19477</noTrafficTravelTimeInSeconds>
            <historicTrafficTravelTimeInSeconds>21463</historicTrafficTravelTimeInSeconds>
            <liveTrafficIncidentsTravelTimeInSeconds>21506</liveTrafficIncidentsTravelTimeInSeconds>
          </routeSummary>
        </response>
      </cell>
      <cell>
        <statusCode>400</statusCode>
        <response>Engine error while executing route request: MAP_MATCHING_FAILURE</response>
      </cell>
    </row>
    <row>
      <cell>
        <statusCode>200</statusCode>
        <response>
          <routeSummary>
            <lengthInMeters>423638</lengthInMeters>
            <travelTimeInSeconds>16161</travelTimeInSeconds>
            <trafficDelayInSeconds>46</trafficDelayInSeconds>
            <departureTime>2018-08-10T10:17:49+02:00</departureTime>
            <arrivalTime>2018-08-10T14:47:09+02:00</arrivalTime>
            <noTrafficTravelTimeInSeconds>15072</noTrafficTravelTimeInSeconds>
            <historicTrafficTravelTimeInSeconds>16119</historicTrafficTravelTimeInSeconds>
            <liveTrafficIncidentsTravelTimeInSeconds>16161</liveTrafficIncidentsTravelTimeInSeconds>
          </routeSummary>
        </response>
      </cell>
      <cell>
        <statusCode>200</statusCode>
          <response>
            <routeSummary>
              <lengthInMeters>836087</lengthInMeters>
              <travelTimeInSeconds>29608</travelTimeInSeconds>
              <trafficDelayInSeconds>181</trafficDelayInSeconds>
              <departureTime>2018-08-10T10:17:49+02:00</departureTime>
              <arrivalTime>2018-08-10T18:31:16+02:00</arrivalTime>
              <noTrafficTravelTimeInSeconds>26776</noTrafficTravelTimeInSeconds>
              <historicTrafficTravelTimeInSeconds>29447</historicTrafficTravelTimeInSeconds>
              <liveTrafficIncidentsTravelTimeInSeconds>29608</liveTrafficIncidentsTravelTimeInSeconds>
            </routeSummary>
          </response>
        </cell>
      </row>
    </matrix>
  <summary>
    <successfulRoutes>3</successfulRoutes>
    <totalRoutes>4</totalRoutes>
  </summary>
</matrixResponse>

JSON Response

{
  "formatVersion": "0.0.1",
  "matrix": [
    [
      {
        "statusCode": 200,
        "response": {
          "routeSummary": {
            "lengthInMeters": 495,
            "travelTimeInSeconds": 135,
            "trafficDelayInSeconds": 0,
            "departureTime": "2018-08-10T10:20:42+02:00",
            "arrivalTime": "2018-08-10T10:22:56+02:00",
            "noTrafficTravelTimeInSeconds": 134,
            "historicTrafficTravelTimeInSeconds": 135,
            "liveTrafficIncidentsTravelTimeInSeconds": 135
          }
        }
      },
      {
        "statusCode": 400,
        "response": "Engine error while executing route request: MAP_MATCHING_FAILURE"
      }
    ],
    [
      {
        "statusCode": 200,
        "response": {
          "routeSummary": {
            "lengthInMeters": 338,
            "travelTimeInSeconds": 105,
            "trafficDelayInSeconds": 0,
            "departureTime": "2018-08-10T10:20:42+02:00",
            "arrivalTime": "2018-08-10T10:22:27+02:00",
            "noTrafficTravelTimeInSeconds": 104,
            "historicTrafficTravelTimeInSeconds": 105,
            "liveTrafficIncidentsTravelTimeInSeconds": 105
          }
        }
      },
      {
        "statusCode": 200,
        "response": {
          "routeSummary": {
            "lengthInMeters": 681999,
            "travelTimeInSeconds": 25106,
            "trafficDelayInSeconds": 1769,
            "departureTime": "2018-08-10T10:20:42+02:00",
            "arrivalTime": "2018-08-10T17:19:07+02:00",
            "noTrafficTravelTimeInSeconds": 21031,
            "historicTrafficTravelTimeInSeconds": 23569,
            "liveTrafficIncidentsTravelTimeInSeconds": 25106
          }
        }
      }
    ]
  ],
  "summary": {
    "successfulRoutes": 3,
    "totalRoutes": 4
  }
}

Successful Response fields

Field Description
matrixResponse The XML root element of the Matrix Response.
matrix A set of rows containing results of route summary calculations.
row Every row represents a set of results of route summary calculations done for a single origin.
cell A single result of route summary calculation.
statusCode The status code of a Response for a route summary calculation.
response Contains a result of the route summary calculation or an error message.
detailedError Contains detailed information about route summary calculation failure (if available in the route summary calculation error response).
routeSummary Contains a result of the route summary calculation.
lengthInMeters Element of routeSummary. The route length in meters.
trafficDelayInSeconds Element of routeSummary. The delay in seconds compared to free-flow conditions according to real-time traffic information.
departureTime Element of routeSummary. The estimated departure time for the route. Specified as a dateTime.
arrivalTime Element of routeSummary. The estimated arrival time for the route. Specified as a dateTime.
travelTimeInSeconds Element of routeSummary. The estimated travel time in seconds. Note that even when traffic=false, travelTimeInSeconds still includes the delay due to traffic.
noTrafficTravelTimeInSeconds Element of routeSummary. The estimated travel time in seconds calculated as if there are no delays on the route due to traffic conditions (e.g., congestion). It will only be present if the routing option computeTravelTimeFor=all will be passed in the Request.
historicTrafficTravelTimeInSeconds Element of routeSummary. The estimated travel time in seconds calculated using time-dependent historic traffic data. It will only be present if the routing option computeTravelTimeFor=all will be passed in the Request.
liveTrafficIncidentsTravelTimeInSeconds Element of routeSummary. The estimated travel time in seconds calculated using real-time speed data. It will only be present if the routing option computeTravelTimeFor=all will be passed in the Request.
summary The summary of the matrix Request.
successfulRoutes The number of successful route calculation Requests.
totalRoutes The total number of processed route calculation Requests.

▲ Return to top

Error Response

The default error Response format is XML. It may be changed by using the Accept header.

Error Response example (XML)

<?xml version="1.0" encoding="UTF-8"?>
<matrixResponse xmlns="http://api.tomtom.com/matrix" formatVersion="0.0.1">
  <error description="Matrix not found for provided id."/>
  <detailedError>
    <code>MatrixNotFound</code>
    <message>Matrix not found for provided id.</message>
  </detailedError>
</matrixResponse>

Error Response example (JSON)

{
  "formatVersion": "0.0.1",
  "error": {
      "description": "Matrix not found for provided id."
  },
  "detailedError": {
    "code": "MatrixNotFound",
    "message": "Matrix not found for provided id."
  }
}

▲ Return to top

Error Response fields

Primary fields
Field Description
formatVersion
string
Version of the matrix error Response format.
error
object
Simplified information about the error.
error{} object
detailedError
object
Detailed information about the error.
detailedError{} object
error{} object
Field Description
description
string
A human-readable description of the error.
It is intended as an aid to developers and is not suitable for exposure to end users.
detailedError{} object
Field Description
code
string
One of the defined error codes.
message
string
A human-readable description of the error code.
It is intended as an aid to developers and is not suitable for exposure to end users.
target
string
Optional.

Target of the particular error.
Values:

  • The name of the Request parameter.
  • postBody
details
array
Optional.

An array of root causes (more detailed errors) that led to this error.
detailedError[] array
innerError
object
Optional.

A higher level of details about this error.
innerError{} object
innerError{} object
Field Description
code
string
One of the defined error codes.
message
string
Optional.

A human-readable representation of the error code.
It is intended as an aid to developers and is not suitable for exposure to end users.
innerError
object
Optional.

A higher level of details about this error.
innerError{} object

▲ Return to top

Error code hierarchy

List of predefined, hierarchical, human-readable error codes.
Top level codes relate to HTTP error codes.
They may be refined by error codes in details or innerError.
Further levels of refinement are possible by nesting innerError inside innerError.

In the future, the list may be extended with additional codes.
The application must be ready for the occurrence of an unknown error code (e.g., by stopping error processing at the last understood level of detail).

Error code Description
InternalServerError Top level code for Requests which ended with HTTP 500 Internal Server Error.
The service cannot handle the Request right now, an unexpected condition was encountered.
MatrixCellError This code may appear inside detailedError object in case of a successfully completed Matrix calculation with failed cell(s), which are not valid
Calculate Route service error responses.
MatrixNotFound Top level code for Requests which ended with HTTP 404 Not Found caused by requesting matrixId which does not exist, or the matrix being already expired.
NotFound Top level code for Requests which ended with HTTP 404 Not Found caused by providing incorrect Request path.
ServiceUnavailable Top level code for Requests which ended with HTTP 503 Service Unavailable.
The service cannot handle the Request right now, this is certainly a temporary state.

▲ Return to top

You are here