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

Matrix Routing

The Routing API - Matrix service allows calculation of a matrix of route summaries for a set of routes defined with origin and destination locations. For every given origin this service calculates the cost of routing from that origin to every given destination. The set of origins and the set of destinations can be thought of as the column and row headers of a table and each cell in the table contains the costs of routing from the origin to the destination for that cell. The following costs are computed for each route:

  • travel times
  • distances

Use the computed costs to determine which routes to calculate using the Routing API.

Example of matrix

For origins: A, B and destinations: X, Y, Z - the following route summaries will be provided in a matrix response in following order:

Origin Destination
A X
A Y
A Z
B X
B Y
B Z

Asynchronous and synchronous matrix processing

You can call Matrix Routing APIs to run either synchronously or asynchronously.

Asynchronous API overview

The asynchronous API is appropriate for processing big volumes of relatively complex routing requests. It allows retrieval of processing results in a separate call (multiple downloads are possible). The asynchronous API is optimized for reliability and is not expected to run into a timeout. Maximum size of matrix for this API is 700 (number of origins multiplied by number of destinations), so examples of matrix dimensions are: 5x10, 10x10, 28x25 (it does not need to be square).

Data retention period notice

Please, be aware that matrices processed by asynchronous API are available for download for 14 days, after which request for results download will return 404 (Not Found) response.

Sequence of asynchronous client actions

  1. Client sends a request to the asynchronous matrix submission endpoint.
  2. The server will respond with one of:
  3. After getting an HTTP 202 or HTTP 303 response the client should follow the redirect to the asynchronous matrix download endpoint which is a blocking long poll request.
  4. Client waits for matrix response, possible scenarios are:
    • Matrix response is calculated before timeout. The client receives HTTP 200. Matrix response is ready and it is being returned to the client.
    • Matrix response is not ready before timeout. The client receives HTTP 202. Matrix request is accepted for processing. The client downloads matrix results from the URL specified by the Location header (see point 3).

Synchronous API overview

The synchronous API is recommended for lightweight routing requests with quickly-expiring results (e.g. due to changing traffic conditions). In such a case, when the service receives a request, it will respond as soon as the route summaries of the matrix are calculated and there will be no possibility to retrieve the results later on. The synchronous API will return a timeout error, if the request takes longer than 60 seconds. Maximum size of matrix is limited to 100 for this API (number of origins multiplied by number of destinations), so examples of matrix dimensions are: 5x10, 10x10, 20x5 (it does not need to be square).

Sequence of synchronous API client actions

  1. Client sends a request to the synchronous matrix endpoint.
  2. The server will respond with one of the following:
    • HTTP 200 Matrix processing result - the calculation is finished before timeout and the client downloads results straight away.
    • HTTP 408 Request timeout error, if the request takes longer than 60 seconds and cannot be finished in this timeframe.
    • HTTP another error (see synchronous matrix HTTP status codes).

 

Asynchronous matrix submission endpoint

This endpoint allows submitting 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.

Matrix submission request

HTTP method and URL

POST https://<baseURL>/routing/<versionNumber>/matrix[/<outputFormat>]?key=<APIKEY>[&redirectMode=<redirectMode>][&routingOption1=<routingValue1>&routingOption2=<routingValue2>...]

Example

https://api.tomtom.com/routing/1/matrix/xml?key=<APIKEY>&routeType=shortest&travelMode=truck

HTTP Headers

The table below describes HTTP request headers of particular interest to Matrix Routing service clients. Required headers must be used or the call will fail. Optional headers, which are highlighted with [square brackets], may be used. If there is a default value that will be assumed when an optional header is not used, it is shown in the table.

Header Description Req'd? Values Default Value
Content-Type Specifies the MIME type of the body of the request. Yes
  • application/xml
  • application/json
[Tracking-ID] 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 RFC4122.

If specified, it is replicated in the Tracking-ID response header.

No

 

Parameters

The table below describes the parameters that can be used in a request. Required parameters must be used or the call will fail. Optional parameters, which are highlighted with [square brackets], may be used. If there is a default value that will be assumed when an optional parameter is not used, it is shown in the table.

Parameter Description Req'd? Type / Values Default Value Max Value
baseURL Base URL for calling the API. Yes api.tomtom.com
versionNumber Service version number. The current value is 1. Yes 1
key Authorization key for access to the API Yes API Key
[outputFormat] The content type of the response structure. No
  • xml
  • json
xml
[redirectMode] Controls the HTTP code of the successful HTTP response to the submission request.

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

In both cases the same Location header is included.

No
  • auto
  • manual
auto
[routingOption] A set of routing options encapsulating parameters modifying a route calculation behaviour. Can be specified multiple times. Representing a supported parameter of the Routing service.
Please note that not supported parameters are:

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

Routing's POST Data Parameters may be delivered using post field. For details please check Matrix Routing POST body definition.

No  

 

POST body

The POST body of matrix request should contain a set of items which will be used to execute requests to the Routing API service.

Required fields must be used or the call will fail. Optional fields, which are highlighted with [square brackets], may be used. If there is a default value that will be assumed when an optional parameter is not used, it is shown in the table.

POST body format

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>

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

Field Description
matrixRequest 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.
[options] A set of options.
[post] Contains data that is passed to 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 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 POST Data Parameters section of Calculate Route services documentation for detailed descriptions and examples of XML and JSON content for this field.

POST body example

XML:

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

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

 

Matrix submission response

On a successful matrix request submission the Matrix Routing service responds with an HTTP 303 redirect to matrix download endpoint. Response has a Location header with link to that endpoint and no body.

Response Codes

Code Meaning and Possible Causes
202

Accepted: a HTTP response with Location header, which 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 Location header, which 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 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. 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.
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.

 

Response Headers

Header Description Values
Location Indicates the location where the matrix results can be downloaded. URI
Access-Control-Expose-Headers A comma separated list of HTTP header names that browsers are allowed to access. Content-Length
Access-Control-Allow-Origin A header instructing browsers to allow customer websites to contact the Matrix Routing service. *
Content-Encoding The Matrix Routing service applies gzip compression to the responses, if it is requested by the client with the Accept-Encoding header. gzip
Content-Type The format of the response as chosen by the client (see the contentType request parameter).
  • application/xml; charset=utf-8
  • 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.

Error response example

The submission endpoint will return error responses with content type depending on the outputFormat parameter.

XML:

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

JSON:

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

Error response fields

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

 

Asynchronous matrix download endpoint

This endpoint fetches results of the asynchronous matrix processing. It responds with HTTP 200 and the matrix results assuming matrix request processing has completed, or HTTP 202 Accepted if the matrix is still being processed. HTTP 202 Accepted will be obtained after 120 s, then client should retry request by following the Location header. An HTTP 200 response does not indicate that every matrix cell succeeded, only that the matrix calculation was completed. Detailed information about the success or failure of the individual calculations of the requested route summaries within the matrix is provided in the HTTP 200 response.

The matrix download GET request is a blocking long poll request.

Matrix download request

HTTP method and URL

GET https://<baseURL>/routing/<versionNumber>/matrix/<matrixId>?key=<APIKEY>

Example

https://api.tomtom.com/routing/1/matrix/<matrixId>?key=<APIKEY>

HTTP Headers

The table below describes HTTP request headers of particular interest to Matrix Routing service clients. Required headers must be used or the call will fail. Optional headers, which are highlighted with [square brackets], may be used. If there is a default value that will be assumed when an optional header is not used, it is shown in the table.

Header Description Req'd? Values Default Value
[Accept-Encoding] Should contain list of encodings acceptable by the client. Usually used to demand a compressed response. No gzip
[Tracking-ID] 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 RFC4122.

If specified, it is replicated in the Tracking-ID response header.

No

Parameters

The table below describes the parameters that can be used in a request. Required parameters must be used or the call will fail. Optional parameters, which are highlighted with [square brackets], may be used. If there is a default value that will be assumed when an optional parameter is not used, it is shown in the table.

Parameter Description Req'd? Type / Values Default Value Max Value
baseURL Base URL for calling the API. Yes api.tomtom.com
versionNumber Service version number. The current value is 1. Yes 1
key Authorization key for access to the API Yes API Key
matrixId Unique id of the matrix, returned in HTTP Location header of Matrix Submission response Yes String

 

Matrix download response

Response Codes

Code Meaning and Possible Causes
200 OK: The matrix calculation has completed. Results are streamed to the client.
202 Accepted: The request has been accepted for processing, but the processing has not been completed. A Location header is added to the response containing a link to retry later.
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, for example a matrix with provided matrixId does not exist.
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.

 

HTTP Headers

The table below lists HTTP response headers of particular interest to Routing API service clients.

Header Description Values
Location Indicates the location where the matrix results can be downloaded. Available only if the response is HTTP 202. URI
Access-Control-Expose-Headers A comma separated list of HTTP header names that browsers are allowed to access. Content-Length
Access-Control-Allow-Origin A header instructing browsers to allow customer websites to contact the Matrix Routing service. *
Content-Encoding The Matrix Routing service applies gzip compression to the responses, if it is requested by the client with the Accept-Encoding header. gzip
Content-Type The format of the response as chosen by the client (see the contentType request parameter).
  • application/xml; charset=utf-8
  • 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.

 

Successful response example

XML:

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

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

Successful response fields

Field Description
matrixResponse 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 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, for details see Routing API.
trafficDelayInSeconds Element of routeSummary, for details see Routing API.
departureTime Element of routeSummary, for details see Routing API.
arrivalTime Element of routeSummary, for details see Routing API.
travelTimeInSeconds Element of routeSummary, for details see Routing API.
noTrafficTravelTimeInSeconds Element of routeSummary, for details see Routing API. It will only be present if routing option computeTravelTimeFor=all will be passed in request.
historicTrafficTravelTimeInSeconds Element of routeSummary, for details see Routing API. It will only be present if routing option computeTravelTimeFor=all will be passed in request.
liveTrafficIncidentsTravelTimeInSeconds Element of routeSummary, for details see Routing API. It will only be present if routing option computeTravelTimeFor=all will be passed in request.
summary Summary of the matrix request.
successfulRoutes Number of successful route calculation requests.
totalRoutes Total number of processed route calculation requests.

 

Error response example

Result download endpoint error responses will be always XML.

XML:

<?xml version="1.0" encoding="UTF-8"?>
<matrixResponse xmlns="http://api.tomtom.com/matrix" formatVersion="0.0.1">
    <error description="Matrix not found for provided id."/>
</matrixResponse>

Structure of an error response

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

 

Synchronous matrix endpoint

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

Request

HTTP method and URL

POST https://<baseURL>/routing/<versionNumber>/matrix/sync[/<outputFormat>]?key=<APIKEY>[&routingOption1=<routingValue1>&routingOption2=<routingValue2>...]

Example

https://api.tomtom.com/routing/1/matrix/sync/xml?key=<APIKEY>&routeType=shortest&travelMode=truck

HTTP Headers

The table below describes HTTP request headers of particular interest to Matrix Routing service clients. Required headers must be used or the call will fail. Optional headers, which are highlighted with [square brackets], may be used. If there is a default value that will be assumed when an optional header is not used, it is shown in the table.

Header Description Req'd? Values Default Value
Content-Type Specifies the MIME type of the body of the request. Yes
  • application/xml
  • application/json
[Accept-Encoding] Should contain list of encodings acceptable by the client. Usually used to demand a compressed response. No gzip

 

Parameters

The table below describes the parameters that can be used in a request. Required parameters must be used or the call will fail. Optional parameters, which are highlighted with [square brackets], may be used. If there is a default value that will be assumed when an optional parameter is not used, it is shown in the table.

Parameter Description Req'd? Type / Values Default Value Max Value
baseURL Base URL for calling the API. Yes api.tomtom.com
versionNumber Service version number. The current value is 1. Yes 1
key Authorization key for access to the API Yes API Key
[outputFormat] The content type of the response structure. No
  • xml
  • json
xml
[routingOption] A set of routing options encapsulating parameters modifying a route calculation behaviour. Can be specified multiple times. Representing a supported parameter of the Routing API service.
Please note that not supported parameters are:

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

Routing's POST Data Parameters may be delivered using post field. For details please check Matrix Routing POST body definition.

No  

 

POST body

The POST body of matrix request should contain a set of items which will be used to execute requests to the Routing API service.

Required fields must be used or the call will fail. Optional fields, which are highlighted with [square brackets], may be used. If there is a default value that will be assumed when an optional parameter is not used, it is shown in the table.

POST body format

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>

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

Field Description
matrixRequest 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.
[options] A set of options.
[post] Contains data that is passed to 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 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 POST Data Parameters section of Calculate Route services documentation for detailed descriptions and examples of XML and JSON content for this field.

 

POST body example

XML:

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

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

HTTP Status Codes

Code Meaning and Possible Causes
200 OK: The matrix calculation has completed. Results are streamed to 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 POST.
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.

 

HTTP Headers

The table below lists HTTP response headers of particular interest to the Routing API service clients.

Header Description Values
Access-Control-Expose-Headers A comma separated list of HTTP header names that browsers are allowed to access. Content-Length
Access-Control-Allow-Origin A header instructing browsers to allow customer websites to contact the Matrix Routing service. *
Content-Encoding The Matrix Routing service applies gzip compression to the responses, if it is requested by the client with the Accept-Encoding header. gzip
Content-Type The format of the response as chosen by the client (see the contentType request parameter).
  • application/xml; charset=utf-8
  • application/json; charset=utf-8

 

Successful response example

XML:

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

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

Successful response fields

Field Description
matrixResponse 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 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, for details see Routing API.
trafficDelayInSeconds Element of routeSummary, for details see Routing API.
departureTime Element of routeSummary, for details see Routing API.
arrivalTime Element of routeSummary, for details see Routing API.
travelTimeInSeconds Element of routeSummary, for details see Routing API.
noTrafficTravelTimeInSeconds Element of routeSummary, for details see Routing API. It will only be present if routing option computeTravelTimeFor=all will be passed in request.
historicTrafficTravelTimeInSeconds Element of routeSummary, for details see Routing API. It will only be present if routing option computeTravelTimeFor=all will be passed in request.
liveTrafficIncidentsTravelTimeInSeconds Element of routeSummary, for details see Routing API. It will only be present if routing option computeTravelTimeFor=all will be passed in request.
summary Summary of the matrix request.
successfulRoutes Number of successful route calculation requests.
totalRoutes Total number of processed route calculation requests.

 

Error response example

The error responses content type depends on the outputFormat parameter.

XML:

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

JSON:

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

Error response fields

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