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

Asynchronous Matrix Download

 

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

Purpose

This endpoint lets clients download the result of their matrix job.

  • A matrix job Id is required for a result download. This Id is available inside the body of a successful Asynchronous Matrix Submission response.
  • To download the result, the job must be in the Completed state.
  • The current state of a job may be checked using the Asynchronous Matrix Status endpoint.
  • The result of a completed job will be included in the HTTP 200 response body.
  • A result download request for a non-Completed matrix job will end with an HTTP 404 response.
In the future, as the max-allowed matrix size increases, this endpoint may redirect the client to another location for the matrix job result, due to expected larger result data volume.

Request data

HTTPS method: GET

URL example

All of the following parameters are required:

https://baseURL/routing/matrix/versionNumber/async/matrixId/result?key=Your_API_Key

Example

https://api.tomtom.com/routing/matrix/2/async/00-00000000-0000-0000-0000-000000000000-0000/result?key=Your_API_Key

HTTP request headers

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

Required headers
Header Description
Accept-Encoding Restricts the content codings that are acceptable in the response. This header is required so that the service can apply gzip compression.
Value: gzip
Optional headers
Header Description
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 the 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
The version of the service to call.
Value: 2
matrixJobId
string
Id of the matrix job to check. It is provided in the response body of a submission request.
Value: string
key
string
An API Key valid for the requested service.
Value: Your valid API Key.

▲ Return to top

Response data

HTTP status codes

Code Meaning and possible causes
200 Request successful, matrix job's result will be included in the response body.
403 Forbidden:
  • The API Key is missing, inactive, invalid, not entitled to use Matrix Routing v2 API, or exceeded the available quota.
  • Can also occur when using HTTP instead of HTTPS.
404 The requested resource could not be found, possible reasons:
  • A job with the provided Id exists, but it's not in Completed state.
  • A job with the provided Id doesn't exist.
  • A job with the provided Id did exist, but the retention period has passed.
  • The provided job Id and the API Key do not match.
  • URI path not found.
405 Method Not Allowed: The client used an HTTP method other than GET.
406 Not Acceptable: The client should declare readiness for receiving the gzip compressed response by using the Accept-Encoding header.
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: Quota was exceeded for the API Key.
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 Matrix Routing v2 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 v2 service.
Value: *
Content-Encoding The Matrix Routing v2 service applies gzip compression to the response 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/json;charset=utf-8
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

Structure overview

HTTP 200 OK
{
  "data": [
    {
      "originIndex": integer,
      "destinationIndex": integer,
      "routeSummary": {
        "lengthInMeters": integer,
        "travelTimeInSeconds": integer,
        "trafficDelayInSeconds": integer,
        "departureTime": dateTime,
        "arrivalTime": dateTime
      },
      "detailedError": object
    },
    ...
  ],
  "statistics": {
    "totalCount": integer,
    "successes": integer,
    "failures": integer,
    "failureDetails": [
      {
        "code": string,
        "count": integer
      },
      ...
    ]
  }
}

Example

HTTP 200 OK
{
  "data": [
    {
      "originIndex": 0,
      "destinationIndex": 0,
      "routeSummary": {
        "lengthInMeters": 681999,
        "travelTimeInSeconds": 25106,
        "trafficDelayInSeconds": 1769,
        "departureTime": "2018-08-10T10:20:42+02:00",
        "arrivalTime": "2018-08-10T17:19:07+02:00"
      }
    },
    {
      "originIndex": 0,
      "destinationIndex": 1,
      "detailedError": {
        "code": "CELL_PROCESSING_ERROR",
        "message": "Cell could not be processed",
        "innerError": {
          "code": "MAP_MATCHING_FAILURE",
          "message": "Engine error while executing route request: MAP_MATCHING_FAILURE: Destination (2.2, 2.2)"
        }
      }
    },
    {
      "originIndex": 0,
      "destinationIndex": 2,
      "detailedError": {
        "code": "CELL_PROCESSING_ERROR",
        "message": "Cell could not be processed",
        "innerError": {
          "code": "UNKNOWN",
          "message": "Unknown error occurred"
        }
      }
    }
  ],
  "statistics": {
    "totalCount": 3,
    "successes": 1,
    "failures": 2,
    "failureDetails": [
      {
        "code": "MAP_MATCHING_FAILURE",
        "count": 1
      },
      {
        "code": "UNKNOWN",
        "count": 1
      }
    ]
  }
}

▲ Return to top

Successful response fields

Primary fields
Field Description
data
array
Contains all calculated route summaries for this matrix.
Comparing to the matrix submission body structure, which is two-dimensional, the data structure is flattened to a single dimension. In order to be able to refer to a specific origin/destination pair, also the originIndex and the destinationIndex fields are also available.
data[] array
statistics
object
Optional field, present when the state is Completed.
statistics{} object
data[] array
Field Description
originIndex
integer
Zero-based index of the origin of a route.
destinationIndex
integer
Zero-based index of the destination of a route.
routeSummary
object
Optional field containing the result of a successful route summary calculation.
lengthInMeters
integer
Element of routeSummary. The route length in meters.
trafficDelayInSeconds
integer
Element of routeSummary. The delay in seconds compared to free-flow conditions according to real-time traffic information.
departureTime
dateTime
Element of routeSummary. The estimated departure time for the route. Specified as a dateTime.
arrivalTime
dateTime
Element of routeSummary. The estimated arrival time for the route. Specified as a dateTime.
travelTimeInSeconds
integer
Element of routeSummary. The estimated travel time in seconds. Note that even when traffic=historical, travelTimeInSeconds still includes the delay due to traffic.
detailedError
object
Optional field, present in an HTTP 200 response body only when there was a problem processing a matrix cell. This field describes the details of a failure, per matrix cell. It is possible that the whole matrix job may be completed and the result is downloaded having an HTTP 200 status while at the same time multiple, or even all the cells have failed.

The content of this object is defined the same as in the case of an error response:
detailedError{} object

statistics{} object
Field Description
totalCount
integer
Total number of routes within this matrix.
successes
integer
Number of successful routes within this matrix.
failures
integer
Number of failed routes within this matrix.
failureDetails
array
When there are any failed cells, this field contains the details about the failure(s).
failureDetails[] array
failureDetails[] array
Field Description
code
string
One of the defined error codes.
count
integer
Number of failed route calculations within this matrix caused by errors having given code.

▲ Return to top

Error response

Error response structure overview

{
  "detailedError": {
    "code": string,
    "message": string,
    "details": [
      {
        "code": string,
        "message": string,
        "target": string,
        "details": [
          ...
        ],
        "innerError": {
          "code": string,.
          "message": string,
          "innerError": {
            ...
          }
        }
      },
      ...
    ]
  }
}

Example

HTTP 404 NOT FOUND
{
   "detailedError": {
     "code": "MATRIX_NOT_FOUND",
     "message": "Matrix not found for provided id."
   }
}

▲ Return to top

Error response fields

Primary fields
Field Description
detailedError
object
Detailed information about the error.
detailedError{} object
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. For example, a parameter name, a path to a JSON property, and others. Contents of this field may change over time.
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. New or existing codes may be introduced as children of codes already present in the hierarchy. 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).

Each error code below has a scope assigned. Scope assignment is subject to change and extension. Possible scopes are:

  • job - the error code concerns the whole job.
    It may be included in the optional detailedError structure.
  • cell - the error code concerns failed processing of one of the matrix cells.
    It may be included in the optional data[].detailedError structure.
    Codes in this scope, apart from the CELL_PROCESSING_ERROR code, may also be included in the optional failureDetails[] array.
Error code Description Scope
MATRIX_NOT_FOUND Top level code for requests which failed with an HTTP 404 status code, caused by requesting the Id of a matrix job which does not exist, doesn't match the API key provided, or has the job result not ready or already expired. job
NOT_FOUND Top level code for requests which failed with an HTTP 404 status code, caused by providing an incorrect request path. job
BAD_REQUEST Top level code for requests which failed with an HTTP 400 status code. Currently possible details:
  • BAD_ARGUMENT
job
INTERNAL_SERVER_ERROR Top level code for requests which failed with an HTTP 500 status code. The service cannot handle the request right now, an unexpected condition was encountered. job
SERVICE_UNAVAILABLE Top level code for requests which failed with an HTTP 503 status code. The service cannot handle the request right now, this is certainly a temporary state. job
BAD_ARGUMENT

One of the request parameters did not pass validation.

Currently possible inner errors:
  • INVALID_PARAMETER_VALUE
job, cell
INVALID_PARAMETER_VALUE The value of one of the parameters is invalid. job
CELL_PROCESSING_ERROR This is the top level code for the cell scope.
It is expected to have details about the issue in the innerError or details field.
Currently possible inner errors:
  • OVER_TRANSACTION_LIMIT
  • UNKNOWN
  • MAP_MATCHING_FAILURE
  • NO_ROUTE_FOUND
  • BAD_ARGUMENT
  • CELL_TIMEOUT
cell
OVER_TRANSACTION_LIMIT Client has exceeded the transaction limit.
cell
UNKNOWN Unknown error has occurred.
cell
MAP_MATCHING_FAILURE One of the input points (origin, destination) could not be matched to the map because there is no known drivable section near this point.
cell
NO_ROUTE_FOUND No valid route could be found for the given origin and destination pair.
cell
CELL_TIMEOUT Failed to calculate route summary for the given origin and destination pair within timeout. cell

▲ Return to top