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.

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=*****&routingOption1=routingValue1&routingOption2=routingValue2

Example:

https://api.tomtom.com/routing/1/matrix/json?key=***&routeType=shortest&travelMode=truck

▲ 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 parameters that can be used in a Request.

• 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.

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

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

HTTP Response codes

▲ Return to top

HTTP Response headers

▲ Return to top

Error Response examples

The Matrix Submission endpoint will return error Responses with the content type depending on the outputFormat parameter value.

Error Response (XML)

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

Error Response (JSON)

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

Error response fields