Asynchronous Matrix Submission
Service version: 1
Last edit: 2020.11.29
Deprecation Notice:
Dec 1, 2020:
- All XML capabilities of the Matrix Routing API are deprecated. This includes
- base path parameter
outputFormat
valuexml
- request header
Content-Type
valueapplication/xml
- POST body parameter
post
value formatxml
- base path parameter
- These capabilities will be withdrawn following a 12 month deprecation period.
- The planned withdrawal date is Dec 1, 2021.
- Following withdrawal, requests using this functionality may receive an HTTP error in the response.
On this page
Purpose
This endpoint enables the submission of a new matrix for asynchronous processing. It responds with a redirect to the location at which the matrix results can be obtained when the matrix processing has completed.
Request data
HTTPS method: POST
URL example
For ease of viewing and identification:
- Required constants and parameters are shown in bold text.
- Optional parameters are shown in normal text.
https://baseURL/routing/versionNumber/matrix/outputFormat?key=Your_API_Key&routingOption1=routingValue1&routingOption2=routingValue2&redirectMode=redirectMode&waitTimeSeconds=waitTimeSeconds
Example:
https://api.tomtom.com/routing/1/matrix/json?key=Your_API_Key&routeType=fastest&travelMode=car
HTTP Request headers
The following table describes HTTP Request headers of particular interest to Matrix Routing service clients.
Required headers | |
---|---|
Header | Description |
Content-Type string |
Specifies the MIME type of the body of the Request. Values:
|
Optional headers | |
Header | Description |
Tracking-ID string |
Specifies 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 . |
Optional parameters | |
Parameter | Description |
outputFormat string |
The content type of the Response structure. Default value: xml Deprecated - for details, see a deprecation notice at the top of this page.Other values: json |
routingOption string |
Every routing option encapsulates one of the parameters that modify a route calculation behavior for Matrix. Multiple options can be specified.
|
redirectMode string |
Controls the HTTP code of the successful HTTP Response to the Submission Request. Value:
Location header is included.
|
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. Please note that provided 120 Value: It may be either:
|
POST body
The POST body of a Matrix Request should contain a set of items which will be used to execute requests to the Calculate Route service. The maximum size of a Matrix for this API is 700
(the number of origins multiplied by the number of destinations), so examples of Matrix dimensions are: 5x10
, 10x10
, 28x25
(it does not need to be square).
POST body (XML)
<?xml version="1.0" encoding="utf-8"?>
<matrixRequest>
<origins>
<location><point latitude="latitudeValue" longitude="longitudeValue"/></location>
...
<location><point latitude="latitudeValue" longitude="longitudeValue"/></location>
</origins>
<destinations>
<location><point latitude="latitudeValue" longitude="longitudeValue"/></location>
...
<location><point latitude="latitudeValue" longitude="longitudeValue"/></location>
</destinations>
<options>
<post>...</post>
</options>
</matrixRequest>
POST body (JSON)
{
"origins": [
{
"point": {"latitude": latitudeValue,"longitude": longitudeValue}
},
...
{
"point": {"latitude": latitudeValue,"longitude": longitudeValue}
}
],
"destinations": [
{
"point": {"latitude": latitudeValue,"longitude": longitudeValue}
},
...
{
"point": {"latitude": latitudeValue,"longitude": longitudeValue}
}
],
"options": {
"post": "..."
}
}
POST body fields
Required fields | |
---|---|
Field | Description |
matrixRequest object |
Root object of the Request. Value: A xml element or json object. |
origins float |
A set of origin locations represented by points (lat,lon). Value: lat,lon : At least one origin is required. |
destinations float |
A set of destination locations represented by points (lat,lon). Value: lat,lon : At least one destination is required. |
Optional fields | |
options object |
A set of options. Value: An object containing a set of options. |
post object |
Contains data that is passed to the Calculate Route service using the HTTP POST method.
|
POST body examples
XML POST body example
<?xml version="1.0" encoding="utf-8"?>
<matrixRequest>
<origins>
<location><point latitude="45.458545" longitude="9.150490"/></location>
<location><point latitude="45.403337" longitude="11.050541"/></location>
</origins>
<destinations>
<location><point latitude="48.149853" longitude="11.499931"/></location>
<location><point latitude="50.033688" longitude="14.538226"/></location>
</destinations>
<options>
<post>
<postData>
<avoidVignette>
AUS,CHE
</avoidVignette>
</postData>
</post>
</options>
</matrixRequest>
JSON POST body example
{
"origins": [
{
"point": {"latitude": 45.458545,"longitude": 9.150490}
},
{
"point": {"latitude": 45.403337,"longitude": 11.050541}
}
],
"destinations": [
{
"point": {"latitude": 48.149853,"longitude": 11.499931}
},
{
"point": {"latitude": 50.033688,"longitude": 14.538226}
}
],
"options": {
"post": {
"avoidVignette": [
"AUS",
"CHE"
]
}
}
}
Response data
Matrix Submission Response
On a successful Matrix Request submission, the Matrix Routing service responds with a HTTP 202
or a HTTP 303
. The Response has a Location
header with a link to the Matrix Download endpoint and no body.
HTTP Status codes
Code | Meaning and possible causes |
---|---|
202 |
Accepted:
|
303 |
See Other:
|
400 |
Bad Request: Missing required parameters, parameters did not pass validation, or the matrix size is too large. |
403 |
Forbidden:
|
404 |
Not Found: The requested resource could not be found, but it may be available again in the future. |
405 |
Method Not Allowed: The client used a HTTP method other than POST. |
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. |
HTTP Response headers
The following table lists HTTP Response headers of particular interest to Matrix 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:
|
Location |
Indicates the location where the matrix results can be downloaded. Value: URI |
Tracking-ID |
An identifier for the Request.
An identifier for the Request. |
Error Response
The error Response content type depends on the outputFormat
parameter.
Error Response example (XML)
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<matrixResponse xmlns="http://api.tomtom.com/matrix" formatVersion="0.0.1">
<error description="VParameter redirectMode: mistake is unsupported."/>
<detailedError>
<code>BadRequest</code>
<message>Bad Request</message>
<details>
<detail>
<code>BadArgument</code>
<message>Parameter redirectMode: mistake is unsupported.</message>
<target>redirectMode</target>
<innerError>
<code>InvalidParameterValue</code>
</detail>
</detail>
</details>
</detailedError>
</matrixResponse>
Error Response example (JSON)
{
"formatVersion":"0.0.1",
"error":{
"description":"Parameter redirectMode: mistake is unsupported."
},
"detailedError":{
"code":"BadRequest",
"message":"Bad Request",
"details":[
{
"code":"BadArgument",
"message":"Parameter redirectMode: mistake is unsupported.",
"target":"redirectMode",
"innerError":{
"code":"InvalidParameterValue"
}
}
]
}
}
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:
|
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
|
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. 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 was missing or did not pass validation.
The Possible inner errors:
|
BadRequest |
Top level code for Requests which resulted in a HTTP Possible root causes:
|
IllegalParameter |
Unsupported request parameter was specified. |
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. |
MalformedBody |
POST body has unexpected format. |
MissingRequiredParameter |
One of the required parameters was not provided. |
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. |