Developer

Synchronous Matrix

Service version: 2
Last edit: 2024.10.17
TomTom Maps

Purpose

This endpoint enables the submission of a new matrix job for synchronous processing, which is best suited for fast, small matrices of lightweight route calculations. To calculate larger matrix jobs/heavy route calculations please see the Asynchronous endpoint.

API Limitations

  • Freemium and Pay as you grow pricing plans support up to 200 items (the number of origins multiplied by the number of destinations) in a single matrix.
  • Enterprise pricing plan supports up to 2500 items in a single matrix.
  • Matrices don't need to be square.
Max matrix
size		Max number
of origins		Max number
of destinations		Additional
limits
100100100N/A
200200200

  • All origins and destinations should be contained in an axis-aligned 400 km x 400 km bounding box. Otherwise some matrix cells will be resolved as OUT_OF_REGION.

250010001000

Check our Pricing and Contact Sales for quotas tailored based on your needs.

Types

The following data table describes the complex data types that can be used in the Matrix Routing v2 service.

TypeDescription

point object

Latitude, longitude pair (in EPSG:4326 projection), with the following constraints:

  • Latitude values must be in the range [-90, +90].

  • Longitude values must be in the range [-180, +180].

Example: {"latitude": 52.37245, "longitude": 4.89406}

dateTime
string

A date and time specified in RFC 3339 format with an optional time zone offset.
Example:

  • 2022-12-19T16:39:57

  • 2022-12-19T16:39:57-08:00

Request data

HTTPS method: POST

  • Constants and parameters enclosed in curly brackets { } must be replaced with their values.
  • Please see the following Request parameters section with the required and optional parameters tables for their values. The generic request format is as follows.

URL request format

All of the following parameters are required:

post
URL request format
https://{baseURL}/routing/matrix/{versionNumber}?key={Your_API_Key}

curl command request format

post
curl command request format
curl -XPOST 'https://{baseURL}/routing/matrix/{versionNumber}?key={Your_API_Key}'

Example

post
Example URL request example
https://api.tomtom.com/routing/matrix/2?key={Your_API_Key}

Request headers

The following table describes HTTP request headers of particular interest to Synchronous Matrix Routing v2 service clients.

Required headersDescription
Content-Type

Specifies the MIME type of the body of the request.
Value: application/json

Optional headersDescription
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 the 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.
  • It is only meant to be used for support and does not involve tracking of you or your users in any form.

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.
  • A parameter's data type is beneath its name.
Required parametersDescription

baseURL
string

Base URL for calling the API.
Values:

versionNumber
string

Service version.
Value: The current value is 2.

key
string

An API Key valid for the requested service.
Value: Your valid API Key.

POST body

The POST body of a matrix request should contain a set of items which will be used to calculate a matrix of route summaries.

post
POST body format - JSON
1{
2  "origins": [
3    {
4      "point": {"latitude": latitudeValue, "longitude": longitudeValue}
5    },
6    ...,
7    {
8      "point": {"latitude": latitudeValue, "longitude": longitudeValue}
9    }
10  ],
11  "destinations": [
12    {
13      "point": {"latitude": latitudeValue, "longitude": longitudeValue}
14    },
15    ...,
16    {
17      "point": {"latitude": latitudeValue, "longitude": longitudeValue}
18    }
19  ],
20  "options": {
21    "departAt": dateTime | "any" | "now",
22    "arriveAt": dateTime | "any",
23    "routeType": "fastest",
24    "traffic": "historical" | "live",
25    "travelMode": "car" | "truck" | "pedestrian",
26    "vehicleMaxSpeed": integer,
27    "vehicleWeight": integer,
28    "vehicleAxleWeight": integer,
29    "vehicleLength": float,
30    "vehicleWidth": float,
31    "vehicleHeight": float,
32    "vehicleCommercial": boolean,
33    "vehicleLoadType": [ string, ... ],
34    "vehicleAdrTunnelRestrictionCode": string,
35    "avoid": [ string, ... ]
36  }
37}

POST body fields

This section contains the detailed description of allowed fields in the POST body.

Required fieldsDescription

origins
array

A non-empty list of origin locations represented by points.
Value: An array of locations (latitude, longitude pairs).

destinations
array

A non-empty list of destination locations represented by points.
Value: An array of locations (latitude, longitude pairs).

Mutually exclusive fieldsDescription

departAt
string

The date and time of departure from the origin point.

  • Departure times apart from any and now must be specified as a dateTime in the future.

  • When a time zone offset is not specified, it will be assumed to be that of the origin point for each individual cell.

  • Specifying a value for the departAt parameter or using the default value is recommended for matrices having multiple destinations.

  • The departAt parameter cannot be used in conjunction with arriveAt.

Default value: any if arriveAt is not specified.
Values:

  • any - This mode is tailored to the use case where the time context is irrelevant. The traffic=live parameter value cannot be used together with any.

  • now - The departure time will be set to the processing time of each individual cell. Processing time may be any time between submission and its completion. This mode is best used together with traffic=live, as the service will then always consider the most recent available traffic information during routing.

  • dateTime

arriveAt
string

The date and time of arrival at the destination point.

  • Arrival times apart from any must be specified as a dateTime in the future.

  • When a time zone offset is not specified, it will be assumed to be that of the destination point for each individual cell.

  • Specifying a value for the arriveAt parameter is recommended for matrices having multiple origins.

  • The arriveAt parameter cannot be used in conjunction with departAt.

Values:

  • any - See departAt=any for details.

  • dateTime

traffic
string

Decides how traffic is considered for computing routes.
Default value: historical
Values:

  • historical - Routing and estimated travel time consider historical travel times and long term closures. Traffic jams and short-term closures during the travel time window do not influence routing or travel time.

  • live - In addition to historical travel times, routing and estimated travel time consider traffic jams and short- and long-term closures during the travel time window.


    Note: traffic=live may not be used in conjunction with travel time any, also see arriveAt and departAt.

Optional fieldsDescription

routeType
string

The type of route requested:

  • fastest: Route calculation is optimized by travel time, while keeping the routes sensible. For example, the calculation may avoid shortcuts along inconvenient side roads or long detours that only save very little time.

Note: Only the fastest type is available in the Synchronous Matrix v2. To use other types, check the Asynchronous Matrix Submission endpoint.
Default value: fastest

travelMode
string

The mode of travel for the requested route.
Default value: car
Other values: truck, pedestrian

vehicleMaxSpeed
integer

Maximum speed of the vehicle in kilometers/hour.

  • Must have a value in the range [0, 250].

  • A value of 0 means that an appropriate value for the vehicle will be determined and applied during route planning.


Default value: 0

vehicleWeight
integer

Weight of the vehicle in kilograms. A value of 0 means that weight restrictions are not considered.
Default value: 0

vehicleAxleWeight
integer

Weight per axle of the vehicle in kilograms. A value of 0 means that weight restrictions per axle are not considered.
Default value: 0

vehicleLength
float

Length of the vehicle in meters. A value of 0 means that length restrictions are not considered.
Default value: 0

vehicleWidth
float

Width of the vehicle in meters. A value of 0 means that width restrictions are not considered.
Default value: 0

vehicleHeight
float

Height of the vehicle in meters. A value of 0 means that height restrictions are not considered.
Default value: 0

vehicleCommercial
boolean

Vehicle is used for commercial purposes and thus may not be allowed to drive on some roads.
Default value: false
Other values: true

vehicleLoadType
array

Specifies types of cargo that may be classified as hazardous materials and are restricted from some roads.
Available values are:

  • US Hazmat classes 1 through 9.
  • Generic classifications for use in other countries.

Use these values for routing in the USA:

  • USHazmatClass1: Explosives

  • USHazmatClass2: Compressed gas

  • USHazmatClass3: Flammable liquids

  • USHazmatClass4: Flammable solids

  • USHazmatClass5: Oxidizers

  • USHazmatClass6: Poisons

  • USHazmatClass7: Radioactive

  • USHazmatClass8: Corrosives

  • USHazmatClass9: Miscellaneous

Use these values for routing in all other countries:

  • otherHazmatExplosive: Explosives

  • otherHazmatGeneral: Miscellaneous

  • otherHazmatHarmfulToWater: Harmful to water

Note: The vehicleLoadType and vehicleAdrTunnelRestrictionCode parameters are independent; please provide both if applicable.
Values: An array of any of:

  • USHazmatClass1

  • USHazmatClass2

  • USHazmatClass3

  • USHazmatClass4

  • USHazmatClass5

  • USHazmatClass6

  • USHazmatClass7

  • USHazmatClass8

  • USHazmatClass9

  • otherHazmatExplosive

  • otherHazmatGeneral

  • otherHazmatHarmfulToWater

vehicleAdrTunnelRestrictionCode
string

If vehicleAdrTunnelRestrictionCode is specified, the vehicle is subject to ADR tunnel restrictions.

  • Vehicles with code B are restricted from roads with ADR tunnel categories B, C, D, and E.

  • Vehicles with code C are restricted from roads with ADR tunnel categories C, D, and E.

  • Vehicles with code D are restricted from roads with ADR tunnel categories D and E.

  • Vehicles with code E are restricted from roads with ADR tunnel category E.

  • If vehicleAdrTunnelRestrictionCode is not specified, no ADR tunnel restrictions apply.

Note: The vehicleAdrTunnelRestrictionCode and vehicleLoadType parameters are independent; please provide both if applicable. Values (specify at most one):

  • B

  • C

  • D

  • E

Reference: European Agreement Concerning the International Carriage of Dangerous Goods by Road (ADR), United Nations, 2019, section 1.9.5 and chapter 8.6

avoid
array

Specifies something that the route calculation should try to avoid when determining the route.
Available values are:

  • tollRoads: Avoids toll roads.

  • unpavedRoads: Avoids unpaved roads.

POST body example

post
POST body example - JSON
1{
2  "origins": [
3    {
4      "point": { "latitude": 45.458545, "longitude": 9.15049 }
5    },
6    {
7      "point": { "latitude": 45.403337, "longitude": 11.050541 }
8    }
9  ],
10  "destinations": [
11    {
12      "point": { "latitude": 48.149853, "longitude": 11.499931 }
13    },
14    {
15      "point": { "latitude": 50.033688, "longitude": 14.538226 }
16    }
17  ],
18  "options": {
19    "departAt": "2022-12-19T16:39:57",
20    "traffic": "historical",
21    "travelMode": "truck",
22    "vehicleMaxSpeed": 90,
23    "vehicleWeight": 12000,
24    "vehicleAxleWeight": 4000,
25    "vehicleLength": 13.6,
26    "vehicleWidth": 2.42,
27    "vehicleHeight": 2.4,
28    "vehicleCommercial": true,
29    "vehicleLoadType": ["otherHazmatExplosive", "otherHazmatGeneral"],
30    "vehicleAdrTunnelRestrictionCode": "C",
31    "avoid": ["unpavedRoads"]
32  }
33}

Response data

Synchronous Matrix response

On a successful matrix request submission, the Synchronous Matrix Routing v2 service responds with an HTTP 200. The response is streamed to the client.

HTTP Status codes

CodeMeaning & possible causes
200

OK: Request successful. At least one of the route calculations has completed for the requested origins and destinations before the sync request timeout passed. Results are streamed to the client.

400

Bad Request: Request cannot be processed correctly, because parameters did not pass validation e.g., due to invalid options, size or header values.

403

Forbidden: The API Key is missing, inactive, invalid, not entitled to use Matrix Routing v2 API, or exceeded the available quota. This can also occur when using HTTP instead of HTTPS.

404

Not Found: The requested resource could not be found.

405

Method Not Allowed: The client used an HTTP method other than POST.

408

Request timeout: None of the route calculations completed before the sync request timeout passed. Please retry. If the issue persists, route calculations may be too heavy for the Synchronous endpoint - consider using the Asynchronous endpoint instead, or try splitting into smaller matrices and re-calculate.

414

Requested URI is too long: Indicates that the URI requested by the client is longer than the server is willing to interpret.

415

Unsupported Media Type: The client used an unsupported media type.

429

Too Many Requests: Customer key's quota was exceeded. Please retry later. To increase the key's quota please Contact Sales for values tailored based on your needs.

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

The following table lists HTTP response headers of particular interest to the Synchronous Matrix Routing v2 service clients.

HeaderDescription
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 v2 service.
Value: *

Content-Encoding

The Synchronous Matrix Routing v2 service applies gzip compression to the response if it is requested by the client with the Accept-Encoding header.
Value: gzip

Content-Type

The format of the response.
Value: 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.

  • It is only meant to be used for support and does not involve tracking of you or your users in any form.

Value: An identifier for the request.

Successful response

Response body format - JSON
1HTTP 200 OK
2{
3  "data": [
4    {
5      "originIndex": integer,
6      "destinationIndex": integer,
7      "routeSummary": {
8        "lengthInMeters": integer,
9        "travelTimeInSeconds": integer,
10        "trafficDelayInSeconds": integer,
11        "departureTime": dateTime,
12        "arrivalTime": dateTime
13      },
14      "detailedError": object
15    },
16    ...
17  ],
18  "statistics": {
19    "totalCount": integer,
20    "successes": integer,
21    "failures": integer,
22    "failureDetails": [
23      {
24        "code": string,
25        "count": integer
26      },
27      ...
28    ]
29  }
30}
Response body example - JSON
1HTTP 200 OK
2{
3  "data": [
4    {
5      "originIndex": 0,
6      "destinationIndex": 0,
7      "routeSummary": {
8        "lengthInMeters": 681999,
9        "travelTimeInSeconds": 25106,
10        "trafficDelayInSeconds": 1769,
11        "departureTime": "2018-08-10T10:20:42+02:00",
12        "arrivalTime": "2018-08-10T17:19:07+02:00"
13      }
14    },
15    {
16      "originIndex": 0,
17      "destinationIndex": 1,
18      "detailedError": {
19        "code": "CELL_PROCESSING_ERROR",
20        "message": "Cell could not be processed",
21        "innerError": {
22          "code": "MAP_MATCHING_FAILURE",
23          "message": "Engine error while executing route request: MAP_MATCHING_FAILURE: Destination (2.2, 2.2)"
24        }
25      }
26    },
27    {
28      "originIndex": 0,
29      "destinationIndex": 2,
30      "detailedError": {
31        "code": "CELL_PROCESSING_ERROR",
32        "message": "Cell could not be processed",
33        "innerError": {
34          "code": "UNKNOWN",
35          "message": "Unknown error occurred"
36        }
37      }
38    }
39  ],
40  "statistics": {
41    "totalCount": 3,
42    "successes": 1,
43    "failures": 2,
44    "failureDetails": [
45      {
46        "code": "MAP_MATCHING_FAILURE",
47        "count": 1
48      },
49      {
50        "code": "UNKNOWN",
51        "count": 1
52      }
53    ]
54  }
55}

Successful response fields

Primary fields
FieldDescription

data
array

Contains all calculated route summaries for this matrix. Compared to the matrix submission body structure which is two-dimensional, the data structure is flattened to a single dimension. In order to be able to refer to a specific origin/destination pair, the originIndex and the
destinationIndex fields are also available.
data array

statistics
object

Contains information about statistics for this matrix.
statistics object

data array
FieldDescription

originIndex
integer

Zero-based index of the origin of a route.

destinationIndex
integer

Zero-based index of the destination of a route.

routeSummary
object

Optional field containing the result of a successful route summary calculation.

lengthInMeters
integer

Element of routeSummary. The route length in meters.

trafficDelayInSeconds
integer

Element of routeSummary. The delay in seconds compared to free-flow conditions according to real-time traffic information.

departureTime
dateTime

Element of routeSummary.

  • If departAt or arriveAt is any, then departureTime is absent.

  • In all other cases departureTime contains the estimated departure time for the route. Specified as a dateTime.

arrivalTime
dateTime

Element of routeSummary.

  • If departAt or arriveAt is any, then arrivalTime is absent.

  • In all other cases arrivalTime contains the estimated arrival time for the route. Specified as a dateTime.

travelTimeInSeconds
integer

Element of routeSummary. The estimated travel time in seconds depending on traffic.

  • If traffic=historical, then travelTimeInSeconds
    includes historical travel times on the route.

  • If traffic=live, then travelTimeInSeconds includes historical travel times as well as traffic jams during the travel time window on the route.

detailedError
object

Optional field, present in an HTTP 200 response body only when there was a problem processing a matrix cell. This field describes the details of a failure, per matrix cell. It is possible that the whole synchronous matrix job may be completed with result having an HTTP 200 status while at the same time multiple, or even all the cells have failed.
The content of this object is defined the same as in the case of an error response:
detailedError object.

statistics object
FieldDescription

totalCount
integer

Total number of routes within this matrix.

successes
integer

Number of successful routes within this matrix.

failures
integer

Number of failed routes within this matrix.

failureDetails
array

When there are any failed cells, this field contains the details about the failure(s).
failureDetails array

failureDetails array
FieldDescription

code
string

One of the defined error codes.

count
integer

Number of failed route calculations within this matrix caused by errors having given code.

Error response

Error response format - JSON
1{
2  "detailedError": {
3    "code": string,
4    "message": string,
5    "details": [
6      {
7        "code": string,
8        "message": string,
9        "target": string,
10        "details": [
11          ...
12        ],
13        "innerError": {
14          "code": string,
15          "message": string,
16          "innerError": {
17            ...
18          }
19        }
20      },
21      ...
22    ]
23  }
24}
Error response example - JSON
1HTTP 400 BAD REQUEST
2{
3  "detailedError": {
4    "code": "BAD_REQUEST",
5    "message": "Bad Request",
6    "details": [
7      {
8        "code": "BAD_ARGUMENT",
9        "message": "Error(s) detected in POST body",
10        "target": "postBody",
11        "details": [
12          {
13            "code": "BAD_ARGUMENT",
14            "message": "Ship is not a valid enum value",
15            "target": "postBody:#/options/travelMode"
16          }
17        ]
18      }
19    ]
20  }
21}

Error response fields

Primary fields
FieldDescription

detailedError
object

Detailed information about the error.
detailedError object

detailedError object
FieldDescription

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. For example, a parameter name, a path to a JSON property, and others. Contents of this field may change over time.

details
array

Optional. An array of root causes (more detailed errors) that led to this error.
detailedError object

innerError
object

Optional. A higher level of details about this error.
innerError object

innerError object
FieldDescription

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 or innerError.
  • Further levels of refinement are possible by nesting innerError inside innerError.

In the future, the list may be extended with additional codes. New or existing codes may be introduced as children of codes already present in the hierarchy. 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).

Each of the following error codes has a scope assigned. Scope assignment is subject to change and extension. Possible scopes are:

  • job - the error code concerns the whole job.
  • cell - the error code concerns failed processing of one of the matrix cells.
    • It may be included in the optional data.detailedError structure.
    • Codes in this scope, apart from the CELL_PROCESSING_ERROR code, may also be included in the optional failureDetails array.
Error codeDescriptionScope
NOT_FOUND

Top level code for requests which failed with an HTTP 404 status code, caused by providing an incorrect request path.

job

BAD_REQUEST

Top level code for requests which failed with an HTTP 400 status code.
Current possible details: BAD_ARGUMENT

job

MATRIX_REQUEST_TIMEOUT

Top level code for requests which failed with an HTTP 408 status code. None of the route calculations completed before the sync request timeout passed.

job

TOO_MANY_MATRIX_REQUESTS

Top level code for requests which failed with an HTTP 429 status code. The service got more requests than it could handle with the current customer key's quota.

job

INTERNAL_SERVER_ERROR

Top level code for requests which failed with an HTTP 500 status code. The service cannot handle the request right now, an unexpected condition was encountered.

job

SERVICE_UNAVAILABLE

Top level code for requests which failed with an HTTP 503 status code. The service cannot handle the request right now, this is certainly a temporary state.

job

FORBIDDEN

Top level code for requests which failed with an HTTP 403 status code.
Current possible details: OVER_TRANSACTION_LIMIT

job

BAD_ARGUMENT

One of the request parameters did not pass validation. The optional target
field may contain the name of the related parameter, or the location inside a JSON object in the request POST body.
Current possible details: BAD_ARGUMENT
Current possible inner errors:

  • ILLEGAL_PARAMETER

  • MISSING_REQUIRED_PARAMETER

  • INVALID_PARAMETER_VALUE

job, cell

OVER_TRANSACTION_LIMITClient has exceeded the transaction limit.

job, cell

MALFORMED_BODYPOST body is not properly formatted.

job

ILLEGAL_PARAMETERUnsupported request parameter was specified.

job

MISSING_REQUIRED_PARAMETEROne of the required parameters was not provided.

job

INVALID_PARAMETER_VALUEThe value of one of the parameters is invalid.

job

CELL_PROCESSING_ERROR

This is the top level code for the cell scope. It is expected to have details about the issue in the innerError or details field.
Current possible inner errors:

  • OVER_TRANSACTION_LIMIT

  • UNKNOWN

  • MAP_MATCHING_FAILURE

  • NO_ROUTE_FOUND

  • BAD_ARGUMENT

  • CELL_TIMEOUT

  • OUT_OF_REGION

The NO_ROUTE_FOUND and MAP_MATCHING_FAILURE cell failures are charged like successful route calculations.

cell

UNKNOWN

Unknown error has occurred.

cell

MAP_MATCHING_FAILURE

One of the input points (origin, destination) could not be matched to the map because there is no known drivable section near this point.

cell

NO_ROUTE_FOUNDNo valid route found for the given input parameters.

cell

CELL_TIMEOUT

Failed to calculate route summary for the given origin and destination pair before the sync request timeout passed. The CELL_TIMEOUTs may be caused by:

  • Route calculations may be too heavy for the Synchronous endpoint - consider using the Asynchronous endpoint instead.

  • Customer key's quota may be too small. Contact Sales for quotas tailored based on your needs.

cell

OUT_OF_REGION

The distance between the given origin and destination pair is too long to calculate the route, considering other requested options. See the API Limitations table for more information.

cell