Asynchronous Matrix Download
Purpose
This endpoint lets clients download the result of their matrix job.
- A
matrixJobId
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, or can be downloaded by following the HTTP 302 response Location header.
Jul 15, 2023
From Oct 15, 2023, the download endpoint will respond with HTTP 302 redirection for all matrices. If you are interested in testing that behavior earlier, please contact us.
- A result download request for a non-
Completed
matrix job will end with an HTTP 404 response.
Types
The following data table describes the complex data types that can be used in the Matrix Routing v2 service.
Types | Description |
---|---|
| Latitude, longitude pair (in EPSG:4326 projection), with the following constraints:
Example: |
| A date and time specified in RFC 3339
format with an optional time zone offset.
|
Request data
HTTPS method: GET
- Constants and parameters enclosed in curly brackets { } must be replaced with their values.
- Please see the following Request parameters section with the required and optional parameters tables for their values. The generic request format is as follows.
URL request format
All of the following parameters are required:
https://{baseURL}/routing/matrix/{versionNumber}/async/{matrixJobId}/result?key={Your_API_Key}
URL request example
https://api.tomtom.com/routing/matrix/2/async/00-00000000-0000-0000-0000-000000000000-0000/result?key={Your_API_Key}
curl command request format
curl 'https://{baseURL}/routing/matrix/{versionNumber}/async/{matrixJobId}/result?key={Your_API_Key}'
Request headers
The following table describes HTTP request headers of particular interest to Large-scale Matrix Routing service clients.
Required headers | 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. |
Optional headers | Description |
---|---|
Tracking-ID | Specifies an identifier for the request. It can be used to trace a call.
Value: An |
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 | Description |
---|---|
| Base URL for calling the API.
|
| The version of the service to call. |
| Id of the matrix job to check. It is provided in the response body of a
submission request. |
| An API Key valid for the requested service. |
Response data
HTTP status codes
Code | Meaning & possible causes |
---|---|
200 | Request successful: Matrix job's result will be included in the response body. |
302 | Request successful: Matrix job's result is available at the address given in the Location header. Your HTTP client may perform an automatic redirect, depending on its configuration. |
403 | Forbidden: The API Key is missing, inactive, invalid, not entitled to use Matrix Routing v2 API, or exceeded the available quota. This can also occur when using HTTP instead of HTTPS. |
404 | The requested resource could not be found, possible reasons:
|
405 | Method Not Allowed: The client used an HTTP method other than |
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. |
Response headers
The following table lists HTTP response headers of particular interest to Matrix Routing v2 service clients.
Header | Description |
---|---|
Location | The Location header indicates the URL the client should follow to
download the matrix job's result. |
Access-Control-Expose-Headers | A comma separated list of HTTP header names that browsers are allowed to
access. |
Access-Control-Allow-Origin | A header instructing browsers to allow customer websites to contact the
Matrix Routing v2 service. |
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. |
Content-Type | The format of the response as chosen by the client (see the
|
Tracking-ID | An identifier for the request. If the Tracking-ID |
Successful response
1HTTP 200 OK2{3 "data": [4 {5 "originIndex": integer,6 "destinationIndex": integer,7 "routeSummary": {8 "lengthInMeters": integer,9 "travelTimeInSeconds": integer,10 "trafficDelayInSeconds": integer,11 "departureTime": dateTime,12 "arrivalTime": dateTime13 },14 "detailedError": object15 },16 ...17 ],18 "statistics": {19 "totalCount": integer,20 "successes": integer,21 "failures": integer,22 "failureDetails": [23 {24 "code": string,25 "count": integer26 },27 ...28 ]29 }30}
1HTTP 200 OK2{3 "data": [4 {5 "originIndex": 0,6 "destinationIndex": 0,7 "routeSummary": {8 "lengthInMeters": 681999,9 "travelTimeInSeconds": 25106,10 "trafficDelayInSeconds": 1769,11 "departureTime": "2018-08-10T10:20:42+02:00",12 "arrivalTime": "2018-08-10T17:19:07+02:00"13 }14 },15 {16 "originIndex": 0,17 "destinationIndex": 1,18 "detailedError": {19 "code": "CELL_PROCESSING_ERROR",20 "message": "Cell could not be processed",21 "innerError": {22 "code": "MAP_MATCHING_FAILURE",23 "message": "Engine error while executing route request: MAP_MATCHING_FAILURE: Destination (2.2, 2.2)"24 }25 }26 },27 {28 "originIndex": 0,29 "destinationIndex": 2,30 "detailedError": {31 "code": "CELL_PROCESSING_ERROR",32 "message": "Cell could not be processed",33 "innerError": {34 "code": "UNKNOWN",35 "message": "Unknown error occurred"36 }37 }38 }39 ],40 "statistics": {41 "totalCount": 3,42 "successes": 1,43 "failures": 2,44 "failureDetails": [45 {46 "code": "MAP_MATCHING_FAILURE",47 "count": 148 },49 {50 "code": "UNKNOWN",51 "count": 152 }53 ]54 }55}
Successful response fields
Primary fields | |
---|---|
Field | Description |
| Contains all calculated route summaries for this matrix. Comparing to
the matrix submission body structure, which is two-dimensional, the
|
| Optional field, present when the state is |
data array | |
Field | Description |
| Zero-based index of the origin of a route. |
| Zero-based index of the destination of a route. |
| Optional field containing the result of a successful route summary calculation. |
| Element of |
| Element of |
| Element of |
| Element of |
| Element of
|
| 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: |
statistics object | |
Field | Description |
| Total number of routes within this matrix. |
| Number of successful routes within this matrix. |
| Number of failed routes within this matrix. |
| When there are any failed cells, this field contains
the details about the failure(s). |
failureDetails array | |
Field | Description |
| One of the defined error codes. |
| Number of failed route calculations within this matrix
caused by errors having given |
Error response
1{2 "detailedError": {3 "code": string,4 "message": string,5 "details": [6 {7 "code": string,8 "message": string,9 "target": string,10 "details": [11 ...12 ],13 "innerError": {14 "code": string,.15 "message": string,16 "innerError": {17 ...18 }19 }20 },21 ...22 ]23 }24}
1HTTP 404 NOT FOUND2{3 "detailedError": {4 "code": "MATRIX_NOT_FOUND",5 "message": "Matrix not found for provided id."6 }7}
Error response fields
Primary fields | |
---|---|
Field | Description |
| Detailed information about the error. |
detailedError object | |
Field | Description |
| One of the defined error codes. |
| 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. |
| 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. |
| Optional. An array of root causes (more detailed errors)
that led to this error. |
| Optional. |
innerError object | |
Field | Description |
| One of the defined error codes. |
| 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. |
| Optional. A higher level of details about this error. |
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
orinnerError
. - Further levels of refinement are possible by nesting
innerError
insideinnerError
.
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 of the following error codes 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 optionalfailureDetails
array.
Error code | Description | Scope |
---|---|---|
MATRIX_NOT_FOUND | Top level code for requests which failed with an HTTP
|
|
NOT_FOUND | Top level code for requests which failed with an HTTP |
|
BAD_REQUEST | Top level code for requests which failed with an HTTP |
|
INTERNAL_SERVER_ERROR | Top level code for requests which failed with an HTTP |
|
SERVICE_UNAVAILABLE | Top level code for requests which failed with an HTTP |
|
BAD_ARGUMENT | One of the request parameters did not pass validation.
Current possible inner errors: |
|
INVALID_PARAMETER_VALUE | The value of one of the parameters is invalid. |
|
CELL_PROCESSING_ERROR | This is the top level code for the
The NO_ROUTE_FOUND and MAP_MATCHING_FAILURE cell failures are charged like successful route calculations. |
|
| Client has exceeded the transaction limit. |
|
| Unknown error has occurred. |
|
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. |
|
NO_ROUTE_FOUND | No valid route could be found for the given origin and destination pair. |
|
CELL_TIMEOUT | Failed to calculate route summary for the given origin and destination pair within timeout. |
|
OUT_OF_REGION | The distance between the given origin and destination pair is too long
to calculate the route, considering other requested options. |
|