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

Matrix Routing

The Online Routing - 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 Online Routing API.

Limitations

Maximum size of matrix 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).

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

The Matrix Routing service uses HTTP redirects to serve the results to the client in a single action, if processing of the matrix is completed fast enough.

Sequence of client actions

  1. Client sends a request to the matrix submission endpoint.
  2. The server will respond with one of:
  3. After getting a HTTP 303 response the client should follow the redirect to the 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).

 

Matrix submission endpoint

Submit a new matrix request for processing.

Responds with a redirect to the location at which the matrix results can be obtained when the processing has completed.

Matrix submission request

Format

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

Example

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

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. The order of request headers is not important.

Header Description Req'd? Values Default Value
Content-Type Specifies the MIME type of the body of the request. Yes
  • application/xml
  • application/json

 

Parameters

The table below describes all of 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. The order of request parameters is not important.

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 Online Routing service.
Please note that not supported parameters are:

  • locations
  • maxAlternatives
  • instructionsType
  • language
  • computeBestOrder
  • routeRepresentation
  • vehicleHeading
  • report
  • callback

Also supporting points POST requests are not supported by Matrix Routing. For detailed descriptions refer to the documentation of Online Routing.

No  

 

POST body

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

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>
</matrixRequest>

JSON:

{
    "origins": [
        {
            "point": {"latitude": latitudeValue,"longitude": longitudeValue}
        },
        ...
        {
            "point": {"latitude": latitudeValue,"longitude": longitudeValue}
        }
    ],

    "destinations": [
        {
            "point": {"latitude": latitudeValue,"longitude": longitudeValue}
        },
        ...
        {
            "point": {"latitude": latitudeValue,"longitude": longitudeValue}
        }
    ]
}

POST body example

XML:

<?xml version="1.0" encoding="utf-8"?>
<matrixRequest>
    <origins>
        <location><point latitude="52.36006" longitude="4.85106"/></location>
        <location><point latitude="52.36187" longitude="4.85056"/></location>
    </origins>

    <destinations>
        <location><point latitude="52.36241" longitude="4.85003"/></location>
        <location><point latitude="52.50931" longitude="13.42937"/></location>
    </destinations>
</matrixRequest>

JSON:

{
    "origins": [
        {
            "point": {"latitude": 52.36006,"longitude": 4.85106}
        },
        {
            "point": {"latitude": 52.36187,"longitude": 4.85056}
        }
    ],

    "destinations": [
        {
            "point": {"latitude": 52.36241,"longitude": 4.85003}
        },
        {
            "point": {"latitude": 52.50931,"longitude": 13.42937}
        }
    ]
}

Structure of POST body

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.

 

Matrix submission response

On a successful matrix request submission the Matrix Routing service responds with a 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
303

See Other: a HTTP redirect to the location where the matrix results can be obtained.

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 a HTTP method other than GET (download endpoint) or POST (submission endpoint).
408 Request timeout.
414 Requested URI is too long.
500 An error occured while processing the request. Please try again later.
502 Internal network connectivity issue.
503 Service currently unavailable.
504 Internal network connectivity issue or a request that has taken too long to complete.
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 supports HTTP compression, if requested by the client. 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

 

Matrix download endpoint

Fetch the matrix results, if ready.

Responds with HTTP 200 and the matrix results assuming matrix request processing has completed, or HTTP 202 Accepted if the matrix request is still being processed. A HTTP 200 response does not indicate that every matrix cell succeeded, only that the matrix 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

Format

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

Example

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

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. The order of request headers is not important.

Header Description Req'd? Values Default Value
[Accept-Encoding] Requests that the response be compressed. No gzip

Parameters

The table below describes all of 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. The order of request parameters is not important.

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 response, returned in HTTP 303 See Other HTTP Location header of Matrix Submission response Yes String

 

Matrix download response

Example of a successful response

XML:

<?xml version="1.0" encoding="utf-8"?>
<matrixResponse formatVersion="0.0.1">
    <matrix>
        <row>
            <cell>
                <statusCode>200</statusCode>
                <response>
                    <routeSummary>
                        <lengthInMeters>495</lengthInMeters>
                        <travelTimeInSeconds>142</travelTimeInSeconds>
                        <trafficDelayInSeconds>0</trafficDelayInSeconds>
                        <departureTime>2016-09-02T14:58:40+02:00</departureTime>
                        <arrivalTime>2016-09-02T15:01:17+02:00</arrivalTime>
                        <noTrafficTravelTimeInSeconds>136</noTrafficTravelTimeInSeconds>
                        <historicTrafficTravelTimeInSeconds>142</historicTrafficTravelTimeInSeconds>
                        <liveTrafficIncidentsTravelTimeInSeconds>142</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>338</lengthInMeters>
                        <travelTimeInSeconds>116</travelTimeInSeconds>
                        <trafficDelayInSeconds>0</trafficDelayInSeconds>
                        <departureTime>2016-09-02T14:58:40+02:00</departureTime>
                        <arrivalTime>2016-09-02T15:01:17+02:00</arrivalTime>
                        <noTrafficTravelTimeInSeconds>112</noTrafficTravelTimeInSeconds>
                        <historicTrafficTravelTimeInSeconds>116</historicTrafficTravelTimeInSeconds>
                        <liveTrafficIncidentsTravelTimeInSeconds>116</liveTrafficIncidentsTravelTimeInSeconds>
                    </routeSummary>
                </response>
            </cell>

            <cell>
                <statusCode>200</statusCode>
                <response>
                    <routeSummary>
                        <lengthInMeters>668832</lengthInMeters>
                        <travelTimeInSeconds>23838</travelTimeInSeconds>
                        <trafficDelayInSeconds>0</trafficDelayInSeconds>
                        <departureTime>2016-09-02T14:58:40+02:00</departureTime>
                        <arrivalTime>2016-09-02T15:01:17+02:00</arrivalTime>
                        <noTrafficTravelTimeInSeconds>21732</noTrafficTravelTimeInSeconds>
                        <historicTrafficTravelTimeInSeconds>23402</historicTrafficTravelTimeInSeconds>
                        <liveTrafficIncidentsTravelTimeInSeconds>23838</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":142,
                        "trafficDelayInSeconds": 0,
                        "departureTime": "2016-09-02T15:01:57+02:00",
                        "arrivalTime": "2016-09-02T15:04:34+02:00",
                        "noTrafficTravelTimeInSeconds":136,
                        "historicTrafficTravelTimeInSeconds":142,
                        "liveTrafficIncidentsTravelTimeInSeconds":142
                    }
                }
            },
            {
                "statusCode": 400,
                "response": "Engine error while executing route request: MAP_MATCHING_FAILURE"
            }
        ],
        [
            {
                "statusCode": 200,
                "response": {
                    "routeSummary": {
                        "lengthInMeters":338,
                        "trafficDelayInSeconds": 0,
                        "departureTime": "2016-09-02T15:01:57+02:00",
                        "arrivalTime": "2016-09-02T15:04:34+02:00",
                        "travelTimeInSeconds":116,
                        "noTrafficTravelTimeInSeconds":112,
                        "historicTrafficTravelTimeInSeconds":116,
                        "liveTrafficIncidentsTravelTimeInSeconds":116
                    }
                }
            },
            {
                "statusCode": 200,
                "response": {
                     "routeSummary": {
                        "lengthInMeters":668832,
                        "trafficDelayInSeconds": 0,
                        "departureTime": "2016-09-02T15:01:57+02:00",
                        "arrivalTime": "2016-09-02T15:04:34+02:00",
                        "travelTimeInSeconds":23838,
                        "noTrafficTravelTimeInSeconds":21732,
                        "historicTrafficTravelTimeInSeconds":23402,
                        "liveTrafficIncidentsTravelTimeInSeconds":23838
                    }
                }
            }
        ]
    ],

    "summary": {
        "successfulRoutes": 3,
        "totalRoutes": 4
    }
}

Structure of a successful response

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 Online Routing.
trafficDelayInSeconds Element of routeSummary, for details see Online Routing.
departureTime Element of routeSummary, for details see Online Routing.
arrivalTime Element of routeSummary, for details see Online Routing.
travelTimeInSeconds Element of routeSummary, for details see Online Routing.
noTrafficTravelTimeInSeconds Element of routeSummary, for details see Online Routing. It will only be present if routing option computeTravelTimeFor=all will be passed in request.
historicTrafficTravelTimeInSeconds Element of routeSummary, for details see Online Routing. It will only be present if routing option computeTravelTimeFor=all will be passed in request.
liveTrafficIncidentsTravelTimeInSeconds Element of routeSummary, for details see Online Routing. 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.

 

Example of an error response

The submission endpoint will return error responses with content type depending on the outputFormat parameter. Result download endpoint error responses will be always xml.

XML:

<?xml version="1.0" encoding="utf-8"?>
<matrixResponse formatVersion="0.0.1">
    <error description="Required String parameter 'key' is not present"/>
</matrixResponse>

JSON:

{
  "formatVersion": "0.0.1",
  "error": {
    "description": "Required String parameter 'key' is not present"
  }
}

Structure of an error response

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

 

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 result download 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 a HTTP method other than GET (download endpoint) or POST (submission endpoint).
408 Request timeout.
414 Requested uri is too long.
500 An error occured while processing the request. Please try again later.
502 Internal network connectivity issue.
503 Service currently unavailable.
504 Internal network connectivity issue or a request that has taken too long to complete.
596 Service not found. Request contains an incorrect FQDN and/or path.

 

Response Headers

The table below lists HTTP response headers of particular interest to Online Routing 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 supports HTTP compression, if requested by the client. 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