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

Asynchronous Matrix Submission

 

Service version: 1
Last edit: 2019.09.24

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=*****&routingOption1=routingValue1&routingOption2=routingValue2&redirectMode=redirectMode

Example:

https://api.tomtom.com/routing/1/matrix/json?key=***&routeType=fastest&travelMode=car

▲ Return to top

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:

  • application/xml
  • application/json
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 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.

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
integer
Service version number.
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
Other values: json
routingOption
object
A set of routing options encapsulating parameters that modify a route calculation behaviour.

  • This can be specified multiple times.
  • It represents a supported parameter of the Routing service.

Please note that the following parameters are not supported:

  • locations
  • maxAlternatives
  • instructionsType
  • language
  • computeBestOrder
  • routeRepresentation
  • vehicleHeading
  • report
  • callback
  • minDeviationTime
  • minDeviationDistance
  • alternativeType

Value: Routing's POST data parameters may be delivered using the post parameter field.
For details please check the Matrix routing POST body definition.

redirectMode
string
Controls the HTTP code of the successful HTTP Response to the Submission Request.
Value:

  • When set to auto, HTTP code 303 is returned. The HTTP client may automatically redirect to
    the download endpoint.
  • When set to manual, HTTP code 202 is returned. The HTTP client will not automatically
    redirect to the download endpoint.

In both cases the same Location header is included.

▲ Return to top

POST body

The POST body of a matrix Request should contain a set of items which will be used to execute requests to the Routing 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": "..."
  }
}

▲ Return to top

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.

  • The POST data format must match the Content-Type header of a submitted matrix request i.e.,
    • It should be in the JSON format when Content-Type is set to application/json.
    • It should be in the XML format if Content-Type is set to application/xml.
  • Otherwise, the data will not be interpreted correctly, and all Matrix elements will end with Response code 400.
  • Please refer to the POST Data Parameters section of the Calculate Route service documentation for detailed descriptions and examples of XML and JSON content for this field.

▲ Return to top

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"
      ]
    }
  }
}

▲ Return to top

Response data

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 Response codes

Code Meaning and possible causes
202 Accepted:

  • A HTTP Response with a Location header that points
    where the matrix results can be obtained.
  • This code is used when redirectMode is set to manual.
303 See Other:

  • A HTTP Response with a Location header that points
    where the matrix results can be obtained.
  • This code is used when redirectMode is set to auto.
400 Bad Request: Missing required parameters, parameters didn't pass validation, or the matrix size is too large.
403 Forbidden: The API Key is missing, inactive, invalid, not entitled to use the Matrix Routing API, over QPS, or over QPD. This can also occur when using HTTP instead of HTTPS.
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 an HTTP method other than POST.
414 Requested URI is too long.
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

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

Value: An identifier for the Request.

▲ Return to top

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"
        }
      }
    ]
  }
}

▲ 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 was missing or did not pass validation.
The target field contains the name of the related parameter.

Possible inner errors:

  • MissingRequiredParameter
  • InvalidParameterValue
  • IllegalParameter
BadRequest

Top level code for Requests which ended with HTTP 400 Bad Request.

Possible root causes:

  • BadArgument
  • MalformedBody
IllegalParameter Unsupported request parameter was specified.
InvalidParameterValue The value of one of the parameters is invalid.
InternalServerError Top level code for Requests which ended with 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 ended with HTTP 404 Not Found caused by providing incorrect Request path.
ServiceUnavailable Top level code for Requests which ended with HTTP 503 Service Unavailable.
The service cannot handle the request right now, this is certainly a temporary state.

▲ Return to top

You are here