Asynchronous Matrix Submission

Service version: 1
Last edit: 2019.11.29

On this page

Purpose

This endpoint enables the submission of 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.

Request data

HTTPS method: POST

URL example

For ease of viewing and identification:

• Required constants and parameters are shown in bold text.
• Optional parameters are shown in normal text.

https://baseURL/routing/versionNumber/matrix/outputFormat?key=Your_API_Key&routingOption1=routingValue1&routingOption2=routingValue2&redirectMode=redirectMode&waitTimeSeconds=waitTimeSeconds

Example:

https://api.tomtom.com/routing/1/matrix/json?key=Your_API_Key&routeType=fastest&travelMode=car

▲ Return to top

HTTP Request headers

The following table describes HTTP Request headers of particular interest to Matrix Routing service clients.

Request parameters

The following table describes the Request parameters.

• Required parameters must be used or the call will fail.
• Optional parameters may be used.
• A parameter's data type is beneath its name.

▲ Return to top

POST body

The POST body of a matrix Request should contain a set of items which will be used to execute requests to the Routing service. The maximum size of a matrix for this API is 700 (the number of origins multiplied by the number of destinations), so examples of matrix dimensions are: 5x10, 10x10, 28x25 (it does not need to be square).

POST body (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>

POST body (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": "..."
  }
}

▲ Return to top

POST body fields

▲ Return to top

POST body examples

XML POST body example

<?xml version="1.0" encoding="utf-8"?>
<matrixRequest>
  <origins>
    <location><point latitude="45.458545" longitude="9.150490"/></location>
    <location><point latitude="45.403337" longitude="11.050541"/></location>
  </origins>

  <destinations>
    <location><point latitude="48.149853" longitude="11.499931"/></location>
    <location><point latitude="50.033688" longitude="14.538226"/></location>
  </destinations>

  <options>
    <post>
      <postData>
        <avoidVignette>
          AUS,CHE
        </avoidVignette>
      </postData>
    </post>
  </options>
</matrixRequest>

JSON POST body example

{
  "origins": [
    {
      "point": {"latitude": 45.458545,"longitude": 9.150490}
    },
    {
      "point": {"latitude": 45.403337,"longitude": 11.050541}
    }
  ],

  "destinations": [
    {
      "point": {"latitude": 48.149853,"longitude": 11.499931}
    },
    {
      "point": {"latitude": 50.033688,"longitude": 14.538226}
    }
  ],

  "options": {
    "post": {
      "avoidVignette": [
        "AUS",
        "CHE"
      ]
    }
  }
}

▲ Return to top

Response data

Matrix Submission Response

On a successful Matrix Request submission, the Matrix Routing service responds with a HTTP 202 or a HTTP 303. The Response has a Location header with a link to the Matrix Download endpoint and no body.

HTTP Status codes

▲ Return to top

HTTP Response headers

▲ Return to top

Error Response

The error Response content type depends on the outputFormat parameter.

Error Response example (XML)

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<matrixResponse xmlns="http://api.tomtom.com/matrix" formatVersion="0.0.1">
  <error description="VParameter redirectMode: mistake is unsupported."/>
  <detailedError>
    <code>BadRequest</code>
    <message>Bad Request</message>
    <details>
      <detail>
        <code>BadArgument</code>
        <message>Parameter redirectMode: mistake is unsupported.</message>
        <target>redirectMode</target>
        <innerError>
          <code>InvalidParameterValue</code>
        </detail>
      </detail>
    </details>
  </detailedError>
</matrixResponse>

Error Response example (JSON)

{
  "formatVersion":"0.0.1",
  "error":{
    "description":"Parameter redirectMode: mistake is unsupported."
  },
  "detailedError":{
    "code":"BadRequest",
    "message":"Bad Request",
    "details":[
      {
        "code":"BadArgument",
        "message":"Parameter redirectMode: mistake is unsupported.",
        "target":"redirectMode",
        "innerError":{
          "code":"InvalidParameterValue"
        }
      }
    ]
  }
}

▲ Return to top

Error Response fields

▲ 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. 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).

▲ Return to top