Migration Guide: TomTom Matrix API to TravelTime Time Filter Fast API

1. Introduction

This guide is aimed at helping a migration from the synchronous Matrix Routing v2 API from TomTom, to the Travel Time Matrix (Fast) endpoint.

It covers the main similarities and differences between the two services, covering Features, Request Details, Response Details, and Error Handling.

For the purposes of this comparison, it is assumed that requests to the TomTom Matrix API are large (> 200 locations) and therefore subject to the additional limits associated with larger matrices.

Why migrate to TravelTime?

Larger matrices (1 million locations per request, vs 2,500)
Support for public transit, cycling, and multi-modal options (as well as driving and walking)
Exceptional performance, even for large requests
Fixed cost and unlimited usage, instead of transactional pricing
Permissive caching policy

2. Features Comparison

The table below covers the main features of the two services.

Feature	TomTom API	TravelTime API
Maximum Matrix Size	2,500 (with a max of 1,000 in either dimension)	10 x 100,000
Sync / Async	Synchronous	Synchronous
Transport Modes	Car, Truck, (Pedestrian for smaller matrices)	Car, Pedestrian, Bicycle, Public Transit
Calculated Properties	Travel time, Distance	Travel time, Distance
Time of Day Configuration	Only possible for smaller matrices	Peak and Off Peak options
Pricing	Usage based	Fixed price, unlimited usage
Endpoint Playground	N/A	playground.traveltime.com/travel-time-distance-matrix-fast
Support	Only for Enterprise licences	Included in all licences
Caching	Restricted	Permitted

3. Request Comparison

The sections below cover the main details of the API requests for each service, including endpoint details, authentication, and request structure.

A side-by-side comparison is provided to show how the same 2x2 matrix can be generated using each service.

Endpoint

Feature	TomTom API	TravelTime API
Base URL	`api.tomtom.com/routing/matrix/2`	`api.traveltimeapp.com/v4/time-filter/fast`
API Version	Included in URL path (`/2`)	Included in URL path (`/v4`)
Request Type	POST	POST

Authentication

Feature	TomTom API	TravelTime API
Authentication Method	`key` in query string	`X-Application-Id` and `X-Api-Key` headers
Required Headers	`Content-Type: application/json`	`Content-Type: application/json` `X-Application-Id: {Your_App_ID}` `X-Api-Key: {Your_API_Key}`

Request Body Structure

Feature	TomTom API	TravelTime API
Search Structure	Journeys calculated from all `origins` to all `destinations`	Individual `one-to-many` or `many-to-one` searches grouped in one request
Location Format	Separate `origins` and `destinations` parameters	Single `locations` array with IDs
Coordinate Labels	`latitude` `longitude`	`lat` `lng`
Configuration	Via `options` parameters	Via specific search parameters, which can differ between searches
Transport Type	`travelMode: car / truck`	`transportation: { type:` `driving+ferry /` `cycling+ferry /` `walking+ferry /` `public_transport` `}`
Time of Day Configuration	`departAt: any`	`arrival_time_period: weekday_morning`
Traffic Configuration	`traffic: historical`	N/A
Max Travel Time Configuration	N/A (but all origins and destinations must be contained in a 400km x 400km bounding box)	Set with the `travel_time` parameter, with max value 10,800 (3 hours)
Result Properties	Not specified in request	Explicitly requested via `properties` array

Request Examples

The request examples below both show how to generate the drive times and distances between two origins and two destinations in the UK.

TomTom Matrix API Request Body:

{
    "origins": [
        {
            "point": {
                "latitude": 51.532131,
                "longitude": -0.293897
            }
        },
        {
            "point": {
                "latitude": 51.871461,
                "longitude": -0.435683
            }
        }
    ],
    "destinations": [
        {
            "point": {
                "latitude": 51.749232,
                "longitude": -1.258321
            }
        },
        {
            "point": {
                "latitude": 50.899630,
                "longitude": -1.011401
            }
        }
    ],
    "options": {
        "departAt": "any",
        "traffic": "historical",
        "travelMode": "car"
    }
}

TravelTime API Request Body:

curl -X POST "https://api.traveltimeapp.com/v4/time-filter/fast" \
  -H "Content-Type: application/json" \
  -H "X-Application-Id: {YOUR_APP_ID}" \
  -H "X-Api-Key: {YOUR_APP_KEY}" \
  -d '{
  "locations": [
    {
      "id": "Origin 1",
      "coords": {
        "lat": 51.532131,
        "lng": -0.293897
      }
    },
    {
      "id": "Origin 2",
      "coords": {
        "lat": 51.871461,
        "lng": -0.435683
      }
    },
    {
      "id": "Destination 1",
      "coords": {
        "lat": 51.749232,
        "lng": -1.258321
      }
    },
    {
      "id": "Destination 2",
      "coords": {
        "lat": 50.899630,
        "lng": -1.011401
      }
    }
  ],
  "arrival_searches": {
    "one_to_many": [
      {
        "id": "Origin 1",
        "departure_location_id": "Origin 1",
        "arrival_location_ids": [
          "Destination 1",
          "Destination 2"
        ],
        "travel_time": 10800,
        "arrival_time_period": "weekday_morning",
        "properties": [
          "travel_time",
          "distance"
        ],
        "transportation": {
          "type": "driving"
        }
      },
      {
        "id": "Origin 2",
        "departure_location_id": "Origin 2",
        "arrival_location_ids": [
          "Destination 1",
          "Destination 2"
        ],
        "travel_time": 10800,
        "arrival_time_period": "weekday_morning",
        "properties": [
          "travel_time",
          "distance"
        ],
        "transportation": {
          "type": "driving"
        }
      }
    ]
  }
}

4. Response Comparison

The sections below cover the main details of the API response for each service.

A side-by-side comparison is provided to show how the same 2x2 matrix is returned using each service.

Structure Differences

Feature	TomTom API	TravelTime API
Root Elements	`data` array and `statistics` object	Single `results` array
Result Organization	Flat array with index references	Nested arrays grouped by individual searches
Success / Error Info	Dedicated `statistics` object, with further details of failures in `failureDetails` array	Unreachable locations listed in `unreachable` arrays (one per search)
Entry Identification	Numeric indices (`originIndex`, `destinationIndex`)	String IDs (`search_id`, `id`)
Route Properties	Nested under `routeSummary` object	Nested under `properties` object
Distance Unit Label	`lengthInMeters`	`distance` (in metres)
Travel Time Unit Label	`travelTimeInSeconds`	`travel_time` (in metres)
Additional Data	`trafficDelayInSeconds`	N/A

Response Examples

The response examples below both show the drive times between two origins and two destinations in the UK.

TomTom Matrix API Response:

{
    "data": [
        {
            "originIndex": 0,
            "destinationIndex": 0,
            "routeSummary": {
                "lengthInMeters": 77390,
                "travelTimeInSeconds": 3844,
                "trafficDelayInSeconds": 0
            }
        },
        {
            "originIndex": 0,
            "destinationIndex": 1,
            "routeSummary": {
                "lengthInMeters": 117490,
                "travelTimeInSeconds": 5285,
                "trafficDelayInSeconds": 0
            }
        },
        {
            "originIndex": 1,
            "destinationIndex": 0,
            "routeSummary": {
                "lengthInMeters": 103982,
                "travelTimeInSeconds": 4773,
                "trafficDelayInSeconds": 0
            }
        },
        {
            "originIndex": 1,
            "destinationIndex": 1,
            "routeSummary": {
                "lengthInMeters": 143639,
                "travelTimeInSeconds": 6195,
                "trafficDelayInSeconds": 0
            }
        }
    ],
    "statistics": {
        "totalCount": 4,
        "successes": 4,
        "failures": 0
    }
}

TravelTime API Response:

{
  "results": [
      {
          "search_id": "Origin 1",
          "locations": [
              {
                  "id": "Destination 1",
                  "properties": {
                      "travel_time": 4123,
                      "distance": 81870
                  }
              },
              {
                  "id": "Destination 2",
                  "properties": {
                      "travel_time": 5278,
                      "distance": 109859
                  }
              }
          ],
          "unreachable": []
      },
      {
          "search_id": "Origin 2",
          "locations": [
              {
                  "id": "Destination 1",
                  "properties": {
                      "travel_time": 4932,
                      "distance": 108815
                  }
              },
              {
                  "id": "Destination 2",
                  "properties": {
                      "travel_time": 6107,
                      "distance": 143597
                  }
              }
          ],
          "unreachable": []
      }
  ]
}

5. Error Handling

Both the TravelTIme API and the TomTom API use standard http status codes, such as 503 Service Unavailable and 500 Internal Server Error.

The table below details the main differences in the structures of the error response for each service.

Feature	TomTom API	TravelTime API
Structure	Multiple levels of nesting	Flat with nested `additional_info`
HTTP Status Code	Outside JSON body	Included in JSON body
Root Elements	`detailedError` (containing `code`, `message`, `details`)	`http_status` `error_code` `description` `documentation_link` `additional_info`

Error Message Examples

The response examples below show the error response for a poorly formatted JSON request, with http error code 400.

TomTom Matrix API Response:

{
   "detailedError": {
       "code": "BAD_REQUEST",
       "message": "Bad Request",
       "details": [
           {
               "code": "MALFORMED_BODY",
               "message": "Could not parse matrix request",
               "target": "postBody"
           }
       ]
   }
}

TravelTime API Response:

{
  "http_status": 400,
  "error_code": 3,
  "description": "Failed to parse json - syntax error",
  "documentation_link": "https://docs.traveltime.com/reference/error-codes",
  "additional_info": {
      "syntax_errors": [
          "Unexpected character ('\"' (code 34)): was expecting comma to separate Object entries"
      ]
  }
}

6. Next Steps

If you are looking to migrate from using the TomTom Matrix API to TravelTime, you’ll need to first sign up for an API key.

To help you get up and running, check out some of the links to more resources below.

Endpoint Reference Endpoint Playground SDKs Postman Collection