Migration Guide

Matrix Routing v2 API Migration Guide

This guide will help you migrate from the Matrix Routing API to the Matrix Routing v2 API.

Note: Throughout this guide, the old Matrix Routing API may be referenced as Matrix Routing v1 API, API v1 or simply v1. Similarly, the Matrix Routing v2 API may be referenced as API v2 or simply v2.

Checklist

• Familiarize yourself with the Matrix Routing v2 API endpoint documentation pages.
• Familiarize yourself with the Changes in API limits presented in this guide.
• Check which v1 parameters you use - some may not be currently supported in v2. For details see the Changes in supported parameters section in this guide. If a parameter that you need is not supported, you can let us know using the Contact us form.
• Replace v1 synchronous calls with calls from v2. The Migration of the synchronous request section will be helpful.
• Replace v1 asynchronous calls with calls from v2, keeping in mind that for the asynchronous version there is one more endpoint now and no long polling. The Migration of the asynchronous request section will be helpful.
• Update the response handling, including error handling.

Changes in API limits

Overall, the maximum size of a matrix increases significantly in the Matrix Routing v2 API. However, to have the larger matrices processed, the input must meet some requirements.

The default limits for the Matrix Routing v2 API compared to the limits for the v1 API, together with the requirements, are presented in the following tables.

If you need a higher number of cells, contact us to get a personalized offer.

Synchronous API

Asynchronous API

Changes in supported parameters

This section provides a comparison of the supported parameters between Matrix Routing API v2 and it's predecessor. For details on the usage of the parameters please refer to API endpoint documentation pages.

If a parameter that you'd like to use is not supported, you can let us know using the Contact us form.

New charging model

The Matrix Routing v2 API is charged based on the matrix dimensions.

If both the number of origins and the number of destinations are less than or equal to 5, then multiply the number of origins by the number of destinations to get the number of billable requests. Otherwise, multiply the greater one of the number of origins and the number of destinations by 5 to get the number of billable requests.

Let's have a matrix of size 4 x 5 (4 origins, 5 destinations). Both dimensions are less or equal to 5 so we apply the charging formula by multiplying 4 times 5. It gives 20 billable requests.

Having a matrix of size 8 x 100 (8 origins, 100 destinations), we multiply 100 (greater of two dimensions) by 5 and get 500 billable requests. That's because both origins and destinations dimensions are greater than 5.

Check our Pricing page for request pricing details. Contact Sales in case of any additional questions.

Migration of the synchronous request

This section covers the actions that must be taken to migrate a synchronous Matrix Routing API request to a synchronous Matrix Routing v2 API request.

Please familiarize yourself with changes in API limits and supported parameters first.

Request

In the Matrix Routing v2 API:

• The path and version change.
• There are no request parameters other than the API Key.
• HTTP headers stay the same.

https://api.tomtom.com/routing/1/matrix/sync/json?key={Your_API_Key}&routeType=fastest&travelMode=truck&traffic=true&vehicleMaxSpeed=90&departAt=now

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

Tip: Notice that sync disappears from the path in v2.

POST Payload

Below are examples of a matrix in both v1 and v2 API versions. Notice that:

• The origins and destinations are defined in the same way.
• The configuration defined in the request parameters in v1 moved to the options object in v2.

Matrix Routing API:

1{
2  "origins": [
3    {
4      "point": {
5        "latitude": 45.458546,
6        "longitude": 9.15049
7      }
8    }
9  ],
10  "destinations": [
11    {
12      "point": {
13        "latitude": 48.149853,
14        "longitude": 11.499931
15      }
16    },
17    {
18      "point": {
19        "latitude": 48.033688,
20        "longitude": 11.538226
21      }
22    }
23  ]
24}

Matrix Routing v2 API:

1{
2  "origins": [
3    {
4      "point": {
5        "latitude": 45.458546,
6        "longitude": 9.15049
7      }
8    }
9  ],
10  "destinations": [
11    {
12      "point": {
13        "latitude": 48.149853,
14        "longitude": 11.499931
15      }
16    },
17    {
18      "point": {
19        "latitude": 48.033688,
20        "longitude": 11.538226
21      }
22    }
23  ],
24  "options": {
25    "departAt": "now",
26    "traffic": "live",
27    "travelMode": "truck",
28    "vehicleMaxSpeed": 90
29  }
30}

Response

HTTP codes

The set of HTTP response codes possible for the synchronous endpoint stays the same.

Please refer to Synchronous Matrix endpoint documentation for the complete list.

Response body

Compared to v1, here are the overall JSON structure of the response body changes in Matrix Routing v2 API:

• The formatVersion field was removed.
• The 2-dimensional matrix array representing the cell results was removed. Instead, a flat array data represents cell results.
• The v1's summary object containing successfulRoutes and totalRoutes was replaced in v2 with the statistics object which contains more detailed info than in v1, including: totalCount, successes, failures and the failureDetails array, listing the count for each failure code that occurred.

The presentation of each matrix cell result changes:

• The cell results (elements of mentioned flat data array) are, unlike elements of matrix array in v1, indexed using the fields originIndex and destinationIndex.
• In v1, the elements of matrix had to match ordering of the cells in the request body. In v2, there is no such guarantee since the elements are, as previously stated, explicitly indexed.
• The statusCode field was removed.
• The response wrapper object was removed.

In the following JSON examples you can see the responses for both Matrix versions for the example requests presented earlier:

Matrix Routing API:

1{
2  "formatVersion": "0.0.1",
3  "matrix": [
4    [
5      {
6        "statusCode": 200,
7        "response": {
8          "routeSummary": {
9            "lengthInMeters": 492470,
10            "travelTimeInSeconds": 22815,
11            "trafficDelayInSeconds": 39,
12            "trafficLengthInMeters": 8900,
13            "departureTime": "2022-09-06T12:46:10+02:00",
14            "arrivalTime": "2022-09-06T19:06:25+02:00"
15          }
16        }
17      },
18      {
19        "statusCode": 200,
20        "response": {
21          "routeSummary": {
22            "lengthInMeters": 494986,
23            "travelTimeInSeconds": 23831,
24            "trafficDelayInSeconds": 39,
25            "trafficLengthInMeters": 8900,
26            "departureTime": "2022-09-06T12:46:10+02:00",
27            "arrivalTime": "2022-09-06T19:23:20+02:00"
28          }
29        }
30      }
31    ]
32  ],
33  "summary": {
34    "successfulRoutes": 2,
35    "totalRoutes": 2
36  }
37}

Matrix Routing v2 API:

1{
2  "data": [
3    {
4      "originIndex": 0,
5      "destinationIndex": 0,
6      "routeSummary": {
7        "lengthInMeters": 492470,
8        "travelTimeInSeconds": 22817,
9        "trafficDelayInSeconds": 42,
10        "trafficLengthInMeters": 8900,
11        "departureTime": "2022-09-06T12:44:39+02:00",
12        "arrivalTime": "2022-09-06T19:04:55+02:00"
13      }
14    },
15    {
16      "originIndex": 0,
17      "destinationIndex": 1,
18      "routeSummary": {
19        "lengthInMeters": 494986,
20        "travelTimeInSeconds": 23835,
21        "trafficDelayInSeconds": 42,
22        "trafficLengthInMeters": 8900,
23        "departureTime": "2022-09-06T12:44:39+02:00",
24        "arrivalTime": "2022-09-06T19:21:54+02:00"
25      }
26    }
27  ],
28  "statistics": {
29    "totalCount": 2,
30    "successes": 2,
31    "failures": 0
32  }
33}

Note: Be sure to also check the Response with failed cells and Error response sections at the end of this guide. They equally apply to the synchronous and asynchronous versions of the Matrix Routing v2 API.

Migration of the asynchronous request

This section describes the migration from asynchronous Matrix Routing API to asynchronous Matrix Routing v2 API.

Asynchronous API changes overview

Please familiarize yourself with changes in API limits and supported parameters first.

In addition to API limits and supported parameters changes there also are the following changes:

Fully asynchronous API without long polling

For the asynchronous Matrix Routing v1 API, in the result of a submission, the client would get an HTTP 303 See Other status, redirecting to the result download endpoint. Then long polling would occur, ending either in result download within 120s, or an HTTP 202 Accepted status together with a Location header leading to the same result download endpoint, if the processing is not complete yet.

In case of Matrix Routing v2 API, this behavior changes. In the result of a submission, the client gets a HTTP 202 Accepted status and a jobId in the JSON response body. The jobId needs to be extracted and explicitly used to get the status of processing, or to download the results using the respective Matrix Routing v2 API endpoints.

Such fully asynchronous interaction is well suited for larger jobs now supported by Matrix Routing v2 API.

Changed data retention period

In the Matrix Routing v2 API, the time for which the asynchronous processing results will be available for download is 24 hours from the moment of completing the job. In v1 of the service, it was 2 weeks.

Job submission

Let's first look into how the submission of a matrix job changes in Matrix Routing v2 API.

Async submission request

Comparing it to its predecessor, in the Matrix Routing v2 API:

• The path and version change.
• There are no request parameters other than the API Key.
• HTTP request headers stay the same.

https://api.tomtom.com/routing/1/matrix/json?key={Your_API_Key}&routeType=fastest&travelMode=truck&traffic=true&vehicleMaxSpeed=90&departAt=now

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

Tip: Notice that async appears as the last element of the path in v2.

POST Payload

The following is a JSON example of a matrix in both v1 and v2 versions. Notice that:

• The origins and destinations are defined the same.
• The configuration defined in the request parameters in v1 moved to the options object in v2.

Matrix Routing API:

1{
2  "origins": [
3    {
4      "point": {
5        "latitude": 45.458546,
6        "longitude": 9.15049
7      }
8    }
9  ],
10  "destinations": [
11    {
12      "point": {
13        "latitude": 48.149853,
14        "longitude": 11.499931
15      }
16    },
17    {
18      "point": {
19        "latitude": 48.033688,
20        "longitude": 11.538226
21      }
22    }
23  ]
24}

Matrix Routing v2 API:

1{
2  "origins": [
3    {
4      "point": {
5        "latitude": 45.458546,
6        "longitude": 9.15049
7      }
8    }
9  ],
10  "destinations": [
11    {
12      "point": {
13        "latitude": 48.149853,
14        "longitude": 11.499931
15      }
16    },
17    {
18      "point": {
19        "latitude": 48.033688,
20        "longitude": 11.538226
21      }
22    }
23  ],
24  "options": {
25    "departAt": "now",
26    "traffic": "live",
27    "travelMode": "truck",
28    "vehicleMaxSpeed": 90
29  }
30}

Note: The structure of the submission request JSON payload is the same in both the asynchronous and synchronous Matrix Routing v2 API.

Async submission response

In Matrix Routing v2 API, the response to a submission changes:

• Instead of an HTTP 303 See Other redirect with a Location header, in v2 the client gets an HTTP 202 Accepted response (and no Location header).
• The response has a JSON body, containing a jobId field.

Example submission response body:

1{
2  "jobId": "a1-785bf64e-9161-4d2d-x123-946c1a741adc-0003",
3  "state": "Submitted"
4}

Change in behavior on bad input

In the case of bad input in the body, there is a change in behavior between the asynchronous versions of v1 and v2.

• In v1, the client would get an immediate HTTP 400 Bad Request response to the submission request.
• In v2, the client gets an HTTP 202 Accepted and a jobId in the response body, the same as for a correct submission.
• The client can learn about the bad input after checking the status endpoint for that jobId.

How the Matrix Routing v1 API would respond to the submission request given an incorrect coordinate value:

1HTTP 400 Bad Request
2{
3  "formatVersion": "0.0.1",
4  "error": {
5    "description": "Could not parse matrixRequest: #/destinations/1/point/longitude: 1112.362832 is not less or equal to 180"
6  },
7  "detailedError": {
8    "code": "BadRequest",
9    "message": "Bad Request",
10    "details": [
11      {
12        "code": "MalformedBody",
13        "message": "Could not parse matrixRequest: #/destinations/1/point/longitude: 1112.362832 is not less or equal to 180",
14        "target": "postBody"
15      }
16    ]
17  }
18}

How the Matrix Routing v2 API responds to a submission request given an incorrect coordinate value:

1HTTP 202 Accepted
2{
3  "jobId": "a1-785bf64e-9161-4d2d-x123-946c1a741adc-0003",
4  "state": "Submitted"
5}

As mentioned, the client needs to extract the jobId and call the status endpoint. Only then can they learn about the bad input. The response of such a status call will look like the following JSON example. Read on to learn more about the status endpoint.

1{
2  "jobId": "a1-a0ed1a56-bbc1-427c-9dc7-6f6d4199cf27-0003",
3  "state": "Failed",
4  "detailedError": {
5    "code": "BAD_REQUEST",
6    "message": "Bad Request",
7    "details": [
8      {
9        "code": "BAD_ARGUMENT",
10        "message": "Error(s) detected in POST body",
11        "target": "postBody",
12        "details": [
13          {
14            "code": "BAD_ARGUMENT",
15            "message": "1112.362832 is not less or equal to 180",
16            "target": "postBody:#/destinations/1/point/longitude"
17          }
18        ]
19      }
20    ]
21  }
22}

Error response

Note: Be sure to also check the Error response section at the end of this guide. It equally applies to all of the endpoints of the Matrix Routing v2 API, including Asynchronous Submission.

Job status

Matrix v1 offered long polling for the result download. However, in practice, a common case is that a client does not want to wait for the result like that. Instead, they prefer to check if the result is ready themselves. In v1 there was no dedicated endpoint for that, and the client would use the download endpoint and then assume an HTTP 404 Not Found response as still in progress. Additionally, such a (long-polling) approach does not fit for larger matrix sizes, now offered by v2.

Matrix v2 fixes these problems by introducing fully asynchronous version of API. After an asynchronous submission, the client should extract the jobId and they can then use the new status endpoint to look up the current state of their job. Please refer to the Asynchronous Matrix Status endpoint documentation page for more information.

Example of a call to the status endpoint:

https://api.tomtom.com/routing/matrix/2/async/a1-785bf64e-9161-4d2d-x123-946c1a741adc-0003?key={Your_API_Key}

Tip: Notice that the path part of the call ends with the jobId, there's no state, status suffix or alike.

And the response looks like this. Notice that a summary of failed cells also is available in the response body:

1{
2  "jobId": "a1-976c3dab-44cc-4b71-x123-3e27f53d04fd-0003",
3  "state": "Completed",
4  "statistics": {
5    "totalCount": 2,
6    "successes": 1,
7    "failures": 1,
8    "failureDetails": [
9      {
10        "code": "OUT_OF_REGION",
11        "count": 1
12      }
13    ]
14  }
15}

Possible states

• Submitted - the job has been submitted and awaits input validation. This is the state returned on an asynchronous submission.
• Validated - the job has passed input validation and is being processed.
• Completed - processing is complete, the result can be downloaded.
• Failed - processing failed. Additional details may be available in the response to the status call. The result will not be available for download.

Result download

As mentioned earlier, in v2 the client can first check if the result is available using the Job status endpoint.

Request

Compared to v1, in the Matrix Routing v2 API:

• The path and version change.
• There are no request parameters other than the API Key.
• HTTP request headers stay the same.

https://api.tomtom.com/routing/1/matrix/a1-eb9252cc-b17f-4d80-x123-a7881231a980-0003?key={Your_API_Key}

https://api.tomtom.com/routing/matrix/2/async/a1-976c3dab-44cc-4b71-x123-3e27f53d04fd-0003/result?key={Your_API_Key}

Tip: Notice that in API v2 async appears before the jobId and that the last element of the path is the term result.

Response

HTTP codes

As previously mentioned, API v2 is now fully asynchronous and the download endpoint does not offer long polling. For this reason, the download endpoint will not respond with an HTTP 202 Accepted code anymore.

Please refer to the Asynchronous Download endpoint documentation for the complete list.

Response body

Compared to v1, the overall JSON structure of the response body changes in the Matrix Routing v2 API are:

• The formatVersion field was removed.
• The 2-dimensional matrix array representing the cell results was removed. Instead, a flat data array represents cell results.
• The v1's summary object containing successfulRoutes and totalRoutes was replaced in v2 with the statistics object which contains more detailed info than in v1, including: totalCount, successes, failures and the failureDetails array, listing the count for each failure code that occurred.

The presentation of each matrix cell result change:

• The cell results (elements of mentioned flat data array) are, unlike elements of matrix in v1, indexed using the fields originIndex and destinationIndex.
• In v1, the elements of matrix had to match ordering of the cells in the request body. In v2, there is no such guarantee since the elements are, as previously stated, explicitly indexed.
• The statusCode field was removed.
• The response wrapper object was removed.

In the following JSON blocks you can see the responses of both Matrix API versions for the example requests presented earlier:

Matrix Routing API:

1{
2  "formatVersion": "0.0.1",
3  "matrix": [
4    [
5      {
6        "statusCode": 200,
7        "response": {
8          "routeSummary": {
9            "lengthInMeters": 492470,
10            "travelTimeInSeconds": 22815,
11            "trafficDelayInSeconds": 39,
12            "trafficLengthInMeters": 8900,
13            "departureTime": "2022-09-06T12:46:10+02:00",
14            "arrivalTime": "2022-09-06T19:06:25+02:00"
15          }
16        }
17      },
18      {
19        "statusCode": 200,
20        "response": {
21          "routeSummary": {
22            "lengthInMeters": 494986,
23            "travelTimeInSeconds": 23831,
24            "trafficDelayInSeconds": 39,
25            "trafficLengthInMeters": 8900,
26            "departureTime": "2022-09-06T12:46:10+02:00",
27            "arrivalTime": "2022-09-06T19:23:20+02:00"
28          }
29        }
30      }
31    ]
32  ],
33  "summary": {
34    "successfulRoutes": 2,
35    "totalRoutes": 2
36  }
37}

Matrix Routing v2 API:

1{
2  "data": [
3    {
4      "originIndex": 0,
5      "destinationIndex": 0,
6      "routeSummary": {
7        "lengthInMeters": 492470,
8        "travelTimeInSeconds": 22817,
9        "trafficDelayInSeconds": 42,
10        "trafficLengthInMeters": 8900,
11        "departureTime": "2022-09-06T12:44:39+02:00",
12        "arrivalTime": "2022-09-06T19:04:55+02:00"
13      }
14    },
15    {
16      "originIndex": 0,
17      "destinationIndex": 1,
18      "routeSummary": {
19        "lengthInMeters": 494986,
20        "travelTimeInSeconds": 23835,
21        "trafficDelayInSeconds": 42,
22        "trafficLengthInMeters": 8900,
23        "departureTime": "2022-09-06T12:44:39+02:00",
24        "arrivalTime": "2022-09-06T19:21:54+02:00"
25      }
26    }
27  ],
28  "statistics": {
29    "totalCount": 2,
30    "successes": 2,
31    "failures": 0
32  }
33}

Response with failed cells

Multiple cells can be failed while the response still has an HTTP 200 OK status code, in both the synchronous and asynchronous Matrix Routing v2 API results.

Example:

1{
2  "data": [
3    {
4      "originIndex": 0,
5      "destinationIndex": 0,
6      "routeSummary": {
7        "lengthInMeters": 492470,
8        "travelTimeInSeconds": 22841,
9        "trafficDelayInSeconds": 76,
10        "trafficLengthInMeters": 15983,
11        "departureTime": "2022-09-06T12:50:09+02:00",
12        "arrivalTime": "2022-09-06T19:10:50+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": "OUT_OF_REGION",
23          "message": "Input coordinates out of region"
24        }
25      }
26    }
27  ],
28  "statistics": {
29    "totalCount": 2,
30    "successes": 1,
31    "failures": 1,
32    "failureDetails": [
33      {
34        "code": "OUT_OF_REGION",
35        "count": 1
36      }
37    ]
38  }
39}

Notice that for the failed cells:

• The originIndex and destinationIndex are present.
• The detailedError object is written instead of routeSummary.
• The statistics object contains a filled failureDetails array.

Below is a list of error codes that can appear on cell level in the Matrix Routing v2 API:

• BAD_ARGUMENT
• CELL_TIMEOUT
• MAP_MATCHING_FAILURE
• NO_ROUTE_FOUND
• OVER_TRANSACTION_LIMIT
• OUT_OF_REGION (related to changes in API limits )
• UNKNOWN

See the Asynchronous or the Synchronous endpoint documentation for details.

Note: Keep in mind that NO_ROUTE_FOUND and MAP_MATCHING_FAILURE cell failures are charged like successful route calculations.

Error response

For any of the v2 endpoints, the structure of an error response body changes in the following way.

• The formatVersion field was removed.
• The error field was removed.
• The detailedError and its structure stay, but the values of code, message, and target change.

Depending on the v2 endpoint, while the detailedError structure is the same, the possible content may differ. See the following documentation for details:

• Synchronous Matrix
• Asynchronous Matrix Submission
• Asynchronous Matrix Status
• Asynchronous Matrix Download

Example error response in the Matrix Routing v1 API:

1{
2  "formatVersion": "0.0.1",
3  "error": {
4    "description": "Parameter redirectMode: mistake is unsupported."
5  },
6  "detailedError": {
7    "code": "BadRequest",
8    "message": "Bad Request",
9    "details": [
10      {
11        "code": "BadArgument",
12        "message": "Parameter redirectMode: mistake is unsupported.",
13        "target": "redirectMode",
14        "innerError": {
15          "code": "InvalidParameterValue"
16        }
17      }
18    ]
19  }
20}

Example error response in the Matrix Routing v2 API:

1{
2  "detailedError": {
3    "code": "BAD_REQUEST",
4    "message": "Bad Request",
5    "details": [
6      {
7        "code": "BAD_ARGUMENT",
8        "message": "Error(s) detected in POST body",
9        "target": "postBody",
10        "details": [
11          {
12            "code": "BAD_ARGUMENT",
13            "message": "Ship is not a valid enum value",
14            "target": "postBody:#/options/travelMode"
15          }
16        ]
17      }
18    ]
19  }
20}