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

Synchronous Matrix

 

Service version: 1
Last edit: 2019.02.18

On this page

Purpose

This endpoint allows the submission of a new matrix for synchronous processing. It responds with a matrix processing result or an HTTP 408 Request timeout error, if the processing time exceeds 60 seconds.

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/sync/outputFormat?key=*****&routingOption1=routingValue1&routingOption2=routingValue2...

Example

https://api.tomtom.com/routing/1/matrix/sync/json?key=*****&routeType=shortest&travelMode=truck

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
Accept-Encoding
string
Should contain list of encodings acceptable by the client. Usually used to demand a compressed Response.
Value: gzip
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).
  • If specified, it is replicated in the Tracking-ID Response header.

Value: Tracking-ID

▲ Return to top

Request parameters

The following table describes the parameters that can be used in a Request.

  • 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.
Value: It may be:

  • json
  • xml
routingOption
object
A set of routing options encapsulating parameters modifying a route calculation behaviour.

  • This can be specified multiple times.
  • It represents a supported parameter of the Routing service.
  • Please note: Parameters that are not supported are:
    • locations
    • maxAlternatives
    • instructionsType
    • language
    • computeBestOrder
    • routeRepresentation
    • vehicleHeading
    • report
    • callback
    • minDeviationTime
    • minDeviationDistance
    • alternativeType
  • Routing's POST data parameters may be delivered using the post field. For details, please check the Matrix Routing POST body definition.

Value: string

▲ Return to top

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

XML POST body

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

JSON POST body

{
  "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 (XML)

Required fields
Field Description
matrixRequest The XML root element of the Request.
origins A set of origin locations represented by points (lat,lon). At least one origin is required.
destinations A set of destination locations represented by points (lat,lon). At least one destination is required.
Optional fields
Field Description
options A set of options.
post 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 batch Request i.e., it should be in the JSON format when the Content-Type is set to application/json and 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 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

HTTP Response codes

Code Meaning and Possible Causes
200 OK: The matrix calculation has completed. Results are streamed to the client.
400 Bad Request: Missing required parameters, or parameters didn't pass validation.
403 Forbidden: The API key is missing, inactive, invalid, not entitled to use the Matrix Routing API over QPS, or over QPD. 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 GET.
408 Request timeout.
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

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 batch results can be downloaded.
Value: URI

▲ Return to top

Successful Response examples

Click to expand/collapse the following examples

XML example

<?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 example

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

▲ Return to top

Successful Response fields (XML)

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

The error Response content type depends on the outputFormat parameter value.

Error Response (XML)

<?xml version="1.0" encoding="utf-8"?>
<matrixResponse formatVersion="0.0.1">
  <error description="Output format: csv is unsupported."/>
</matrixResponse>

Error Response (JSON)

{
  "formatVersion": "0.0.1",
  "error": {
    "description": "Output format: csv is unsupported."
  }
}

▲ Return to top

Error response fields

XML Field Description
matrixResponse Root element of the matrix error response.
formatVersion Version of matrix error Response format.
error Element describing the error.
description Description of the error.

▲ Return to top

You are here