Asynchronous Matrix Download

Service version: 1
Last edit: 2019.11.29

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 sent after 120 seconds by default. This behavior can be overridden as needed by passing the waitTimeSeconds parameter with a desired value. The client should then 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=Your_API_Key&waitTimeSeconds=waitTimeSeconds

Example

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

HTTP Request headers

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

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.

▲ Return to top

Response data

HTTP Status codes

▲ Return to top

HTTP Response headers

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

▲ Return to top

Successful Response examples

Click to expand/collapse the following examples

<?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>

{
  "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

▲ 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

▲ 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).

▲ Return to top