Asynchronous Matrix Download

Service version: 1
Last edit: 2019.11.29

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.

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. It is only meant to be used for support and does not involve tracking of you or your users in any form. 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` string	Service version. 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
Parameter	Description
`waitTimeSeconds` integer	Allows changing the maximum amount of time, in seconds, for which the client may have to wait for an Asynchronous Matrix Download Response while the matrix is being calculated. If the matrix processing completes during the given number of seconds, then the matrix processing result is returned. Otherwise, if the matrix is still processing, a HTTP 202 (Accepted) response is returned. The client should then retry the Request by following the `Location` header. Please note that the provided `waitTimeSeconds` parameter and its value are passed to the `Location` response header as a part of the URI. Default value: `120` Value: It may be either: `5..60` `120`

▲ Return to top

Response data

HTTP Status 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 did not pass validation.
`403`	Forbidden: The API Key is missing, inactive, invalid, or not entitled to use Matrix Routing API over QPS (Queries per second) or over QPD (Queries per day). 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 a HTTP method other than GET.
`408`	Request timeout: The request sent to the server took longer than it was prepared to wait.
`414`	Requested URI is too long: Indicates that the URI requested by the client is longer than the server is willing to interpret.
`429`	Too Many Requests: The API Key is over QPS (Queries per second).
`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. It is only meant to be used for support and does not involve tracking of you or your users in any form. 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
`BadArgument`	One of the Request parameters did not pass validation. The `target` field contains the name of the related parameter. Possible inner errors: `InvalidParameterValue` `ValueOutOfRange`
`InvalidParameterValue`	The value of one of the parameters is invalid.
`InternalServerError`	Top level code for Requests which resulted in a 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 resulted in a 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 resulted in a HTTP `404 Not Found` caused by providing incorrect Request path.
`ServiceUnavailable`	Top level code for Requests which resulted in a HTTP `503 Service Unavailable`. The service cannot handle the Request right now, this is certainly a temporary state.
`ValueOutOfRange`	The value of one of the numeric parameters is out of the allowed range.

▲ Return to top

Asynchronous Matrix Download

On this page

Purpose

Request data

HTTPS method: GET

URL example

Example

HTTP Request headers

Request parameters

Response data

HTTP Status codes

HTTP Response headers

Successful Response examples

Click to expand/collapse the following examples

Successful Response fields

Error Response

Error Response example (XML)

Error Response example (JSON)

Error Response fields

Error code hierarchy