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

Synchronous Matrix

 

Service version: 2
Last edit: 2021.09.07

Public Preview Notice

This API is in Public Preview. Go to the Public Preview - what is it? page to see what this means.

On this page

Purpose

This endpoint enables the submission of a new matrix job for synchronous processing. It responds with a matrix processing result or an HTTP 408 request timeout error, if the processing time exceeds 35 seconds.

API Limitations

  • The maximum matrix size limit (the number of origins multiplied by the number of destinations) depends on the pricing plan.
  • The allowed shape of a matrix depends on the time context used in a submission. Time context can be set using the departAt (default) and arriveAt parameters.
  • Matrices don't need to be square.
  • Additional limits apply to Freemium and Pay as you grow pricing plans.
Pricing plan Max matrix size Max origins
when using departAt
(default)
Max destinations
when using arriveAt
Example matrix dimensions Additional limits
Freemium/Pay as you grow 200 10 10
  • 1x200
  • 2x100
  • 10x20
  • 20x10 (with arriveAt specified)
  • May calculate at most 200 matrix items per second.
  • May calculate at most 2500 matrix items per day (affects Freemium only).
Enterprise 2500 50 50
  • 5x10
  • 50x50
  • 1x2500
  • 2500x1 (with arriveAt specified)
N/A

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

Request data

HTTPS method: POST

URL example

All of the following parameters are required:

https://baseURL/routing/matrix/versionNumber?key=Your_API_Key

Example:

https://api.tomtom.com/routing/matrix/2?key=Your_API_Key

▲ Return to top

HTTP request headers

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

Required headers
Header Description
Content-Type
string
Specifies the MIME type of the body of the request.
Value: application/json
Optional headers
Header Description
Tracking-ID
string
Specifies an identifier for the request.
  • It can be used to trace a call.
  • The value must match the regular expression '^[a-zA-Z0-9-]{1,100}$'.
  • An example of 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 parameters
Parameter Description
baseURL
string
Base URL for calling the API.
Value: api.tomtom.com
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.

▲ Return to top

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.

{
  "origins": [
    {
      "point": {"latitude": latitudeValue, "longitude": longitudeValue}
    },
    ...,
    {
      "point": {"latitude": latitudeValue, "longitude": longitudeValue}
    }
  ],
  "destinations": [
    {
      "point": {"latitude": latitudeValue, "longitude": longitudeValue}
    },
    ...,
    {
      "point": {"latitude": latitudeValue, "longitude": longitudeValue}
    }
  ],
  "options": {
    "departAt": dateTime | "any" | "now",
    "arriveAt": dateTime | "any",
    "traffic": "historical" | "live",
    "travelMode": "car" | "truck",
    "vehicleMaxSpeed": integer,
    "vehicleWeight": integer,
    "vehicleAxleWeight": integer,
    "vehicleLength": float,
    "vehicleWidth": float,
    "vehicleHeight": float,
    "vehicleCommercial": boolean,
    "vehicleLoadType": [ string, ... ],
    "vehicleAdrTunnelRestrictionCode": string
  }
}

▲ Return to top

POST body fields

The following fields correspond to parameters listed in Common Routing Parameters. Please consult this page if you wish to know more about particular parameters.

Required fields
Field Description
origins
array
A non-empty list of origin locations.
Value: An array of points (latitude, longitude pairs).
destinations
array
A non-empty list of destination locations.
Value: An array of points (latitude, longitude pairs).
Mutually exclusive fields
Field Description
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.
Other values:
  • any - The Routing API chooses a fixed implementation defined departure time in the near future. Clients must not rely on the specific implementation. This mode is tailored to the usecase where an exact departure time is not known or relevant, nevertheless all cells should have a consistent departure time. Since the precise routing time is not relevant in this mode, live traffic data is therefore not used. 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 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 fields
Field Description
travelMode
string
The mode of travel for the requested route.
Default value: car
Other values: truck
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
vehicleLoadType
array
Specifies types of cargo that may be classified as hazardous materials and are restricted from some roads.
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.
Values:
  • B
  • C
  • D
  • E

▲ Return to top

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": {
    "departAt": "1996-12-19T16:39:57",
    "traffic": "historical",
    "travelMode": "truck",
    "vehicleMaxSpeed": 90,
    "vehicleWeight": 12000,
    "vehicleAxleWeight": 4000,
    "vehicleLength": 13.6,
    "vehicleWidth": 2.42,
    "vehicleHeight": 2.40,
    "vehicleCommercial": true,
    "vehicleLoadType": ["otherHazmatExplosive", "otherHazmatGeneral"],
    "vehicleAdrTunnelRestrictionCode": "C"
  }
}

▲ Return to top

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

Code Meaning and possible causes
200 OK: Request successful, the matrix calculation has completed for the requested origins and destinations. 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.
  • 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: The request sent to the server took longer than it was prepared to wait.
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: Quota was exceeded for the API Key.
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 the Synchronous Matrix Routing v2 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 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.

▲ Return to top

Successful response

Structure overview

HTTP 200 OK
{
  "data": [
    {
      "originIndex": integer,
      "destinationIndex": integer,
      "routeSummary": {
        "lengthInMeters": integer,
        "travelTimeInSeconds": integer,
        "trafficDelayInSeconds": integer,
        "departureTime": dateTime,
        "arrivalTime": dateTime
      },
      "detailedError": object
    },
    ...
  ],
  "statistics": {
    "totalCount": integer,
    "successes": integer,
    "failures": integer,
    "failureDetails": [
      {
        "code": string,
        "count": integer
      },
      ...
    ]
  }
}

Example

HTTP 200 OK
{
  "data": [
    {
      "originIndex": 0,
      "destinationIndex": 0,
      "routeSummary": {
        "lengthInMeters": 681999,
        "travelTimeInSeconds": 25106,
        "trafficDelayInSeconds": 1769,
        "departureTime": "2018-08-10T10:20:42+02:00",
        "arrivalTime": "2018-08-10T17:19:07+02:00"
      }
    },
    {
      "originIndex": 0,
      "destinationIndex": 1,
      "detailedError": {
        "code": "CELL_PROCESSING_ERROR",
        "message": "Cell could not be processed",
        "innerError": {
          "code": "MAP_MATCHING_FAILURE",
          "message": "Engine error while executing route request: MAP_MATCHING_FAILURE: Destination (2.2, 2.2)"
        }
      }
    },
    {
      "originIndex": 0,
      "destinationIndex": 2,
      "detailedError": {
        "code": "CELL_PROCESSING_ERROR",
        "message": "Cell could not be processed",
        "innerError": {
          "code": "UNKNOWN",
          "message": "Unknown error occurred"
        }
      }
    }
  ],
  "statistics": {
    "totalCount": 3,
    "successes": 1,
    "failures": 2,
    "failureDetails": [
      {
        "code": "MAP_MATCHING_FAILURE",
        "count": 1
      },
      {
        "code": "UNKNOWN",
        "count": 1
      }
    ]
  }
}

▲ Return to top

Successful response fields

Primary fields
Field Description
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
Field Description
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. The estimated departure time for the route. Specified as a dateTime.
arrivalTime
dateTime
Element of routeSummary. The estimated arrival time for the route. Specified as a dateTime.
travelTimeInSeconds
integer
Element of routeSummary. The estimated travel time in seconds. Note that even when traffic=historical, travelTimeInSeconds still includes the delay due to traffic.
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
Field Description
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
Field Description
code
string
One of the defined error codes.
count
integer
Number of failed route calculations within this matrix caused by errors having given code.

▲ Return to top

Error response

Error response structure overview

{
  "detailedError": {
    "code": string,
    "message": string,
    "details": [
      {
        "code": string,
        "message": string,
        "target": string,
        "details": [
          ...
        ],
        "innerError": {
          "code": string,
          "message": string,
          "innerError": {
            ...
          }
        }
      },
      ...
    ]
  }
}

Error response example

HTTP 400 BAD REQUEST
{
  "detailedError": {
    "code": "BAD_REQUEST",
    "message": "Bad Request",
    "details": [
      {
        "code": "BAD_ARGUMENT",
        "message": "Error(s) detected in POST body",
        "target": "postBody",
        "details": [
          {
            "code": "BAD_ARGUMENT",
            "message": "Ship is not a valid enum value",
            "target": "postBody:#/options/travelMode"
          }
        ]
      }
    ]
  }
}

▲ Return to top

Error response fields

Primary fields
Field Description
detailedError
object
Detailed information about the error.
detailedError{} object
detailedError{} object
Field Description
code
string
One of the defined error codes.
message
string
A human-readable description of the error code. It is intended as an aid to developers and is not suitable for exposure to end users.
target
string
Optional.
Target of the particular error. 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[] array
innerError
object
Optional.
A higher level of details about this error.
innerError{} object
innerError{} object
Field Description
code
string
One of the defined error codes.
message
string
Optional.
A human-readable representation of the error code. It is intended as an aid to developers and is not suitable for exposure to end users.
innerError
object
Optional.
A higher level of details about this error.
innerError{} object

▲ Return to top

Error code hierarchy

List of predefined, hierarchical, human-readable error codes.

  • Top level codes relate to HTTP error codes.
  • They may be refined by error codes in details or innerError.
  • Further levels of refinement are possible by nesting innerError inside innerError.

In the future, the list may be extended with additional codes. 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 error code below has a scope assigned. Scope assignment is subject to change and extension. Possible scopes are:

  • job - the error code concerns the whole job.
    It may be included in the optional detailedError structure.
  • 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 code Description Scope
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. Currently possible details:
  • BAD_ARGUMENT
job
MATRIX_REQUEST_TIMEOUT Top level code for requests which failed with an HTTP 408 status code. Calculating matrix takes too long to complete using sync mode. Try one of the following:
  • Recalculate using async mode.
  • Split the request into smaller requests.
  • Customer's matrix item calculation per second quota may be too small to fit within the synchronous API timeout.
    See Contact Sales for quotas tailored based on your needs.
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
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.

Currently possible details:
  • BAD_ARGUMENT
Currently possible inner errors:
  • ILLEGAL_PARAMETER
  • MISSING_REQUIRED_PARAMETER
  • INVALID_PARAMETER_VALUE
job, cell
MALFORMED_BODY POST body is not properly formatted. job
ILLEGAL_PARAMETER Unsupported request parameter was specified. job
MISSING_REQUIRED_PARAMETER One of the required parameters was not provided. job
INVALID_PARAMETER_VALUE The 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.
Currently possible inner errors:
  • OVER_TRANSACTION_LIMIT
  • UNKNOWN
  • MAP_MATCHING_FAILURE
  • NO_ROUTE_FOUND
  • BAD_ARGUMENT
  • CELL_TIMEOUT
cell
OVER_TRANSACTION_LIMIT Client has exceeded the transaction limit.
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_FOUND No valid route could be found for the given origin and destination pair.
cell
CELL_TIMEOUT Failed to calculate route summary for the given origin and destination pair within timeout.
  • The route calculation may be heavy and should be done with the asynchronous version of the Matrix Routing v2.
  • Customer's matrix item calculation per second quota may be too small to fit within the synchronous API timeout.
    See Contact Sales for quotas tailored based on your needs.
cell

▲ Return to top