Migration Guide: TomTom Reachable Range API to TravelTime Time Map Fast API

1. Introduction

This guide is aimed at helping a migration from the TomTom Calculate Reachable Range function (from the Routing API), to the Time Map Fast endpoint.

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

Why migrate to TravelTime?

Exceptional performance
Additional public transit, cycling, and walking modes
More detailed isochrones
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 Isoline Size	10,000,000 seconds	3 hours*
Sync / Async	Synchronous	Synchronous
Transport Modes	Car, Truck In Beta - Taxi, Bus, Van, Motorcycle	Car, Pedestrian, Bicycle, Public Transit
Range Types	Travel time, Distance, Fuel, Energy	Travel time, Distance*
Time of Day Configuration	Any time of day	Peak and Off Peak options
Response Formats	JSON Javascript	GeoJSON JSON WKT
Pricing	Usage based	Fixed price, unlimited usage
Endpoint Playground	N/A	playground.traveltime.com/isochrones-fast
Support	Paid	Included in all licences
Caching	Restricted	Permitted

*Distance isolines are supported through a separate Distance Map endpoint

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 one hour driving isochrone can be generated using each service.

Endpoint

Feature	TomTom API	TravelTime API
Base URL	`api.tomtom.com/routing/1/calculateReachableRange`	`api.traveltimeapp.com/v4/time-map/fast`
Primary Request Type	GET POST	POST*

*TravelTime API supports GET requests through the Time Map endpoint

Authentication

Feature	TomTom API	TravelTime API
Authentication Method	`key` in query string	`X-Application-Id` and `X-Api-Key` headers
Required Headers	N/A	`Content-Type: application/json` `X-Application-Id: {Your_App_ID}` `X-Api-Key: {Your_API_Key}`
Optional Headers	`Accept-Encoding: gzip` `Content-Encoding: gzip` `Content-Type: application/json` `Tracking-ID`	`Accept: application/json` (used to adjust the response format - e.g geoJSON, JSON, or WKT)

Request Structure

The primary difference between the request structure is that the TomTom API uses primarily GET requests, with parameters included in the query string (except for a handful of specific parameters). In contrast, the TravelTime API uses POST requests, with parameters included in the request body.

Feature	TomTom API	TravelTime API
Batch Support	N/A	Supported through an array of `one-to-many` or `many-to-one` searches
Arrival vs Departure	Only supports departure searches (travelling away from the origin)	Determined by using either `one_to_many` or `many_to_one` search
Coordinate Input	`latitude, longitude`	`coords: { lat, lng }`
Transport Type	`travelMode: car / truck`	`transportation: { type:` `driving+ferry /` `cycling+ferry /` `walking+ferry /` `public_transport` `}`
Travel Time Configuration	`timeBudgetInSec` (in seconds)	`travel_time` (in seconds)
Time of Day Configuration	`depart_at=2025-01-01T00:00:00Z`	`arrival_time_period: weekday_morning`
Shape Granularity	N/A	Controlled through: `polygons_filter` (remove smaller separated polygons) `level_of_detail` (control the granularity of the shape) `no_holes` (fill in holes in polygons)

Request Examples

The curl examples below both show how to generate a simple one hour driving isochrone departing from a location in New York City.

These requests both include all of the required fields. Both services offer additional optional fields for tailoring the results further.

TomTom API Request:

curl -X GET
"https://api.tomtom.com/routing/1/calculateReachableRange/40.72511,-73.99088/json?timeBudgetInSec=3600&travelMode=car&key={Your_API_Key}"

TravelTime API Request:

curl -X POST https://api.traveltimeapp.com/v4/time-map/fast \
-H 'Content-Type: application/json' \
-H 'Accept: application/geo+json' \
-H 'X-Application-Id: {YOUR_APP_ID}' \
-H 'X-Api-Key: {YOUR_APP_KEY}' \
-d '{
  "arrival_searches": {
    "one_to_many":[
      {
        "id": "Example",
        "coords": {
          "lat": 40.72511,
          "lng": -73.99088
        },
        "arrival_time_period": "weekday_morning",
        "travel_time": 3600,
        "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 one hour driving isochrone is returned using each service.

Structure Differences

Feature	TomTom API	TravelTime API
Response Formats	JSON JSONP	JSON GeoJSON WKT
Support for Holes	N/A	JSON - handled by `holes` arrays GeoJSON - handled natively WKT - handled natively
Support for Multiple Disconnected Polygons	N/A	JSON - handled by multiple `shell` arrays GeoJSON - handled natively WKT - handled natively
Isochrone Style Properties	N/A	N/A

Response Examples

The response examples below both show a one hour driving isochrone from a location in New York City.

For the TravelTime response, geoJSON is used as the response format, but other formats are available (JSON, WKT).

TomTom API Response:

{
   "formatVersion": "0.0.1",
   "reachableRange": {
       "center": {
           "latitude": 40.72514,
           "longitude": -73.99086
       },
       "boundary": [
           {
               "latitude": 41.31908,
               "longitude": -74.06374
           },
           {
               "latitude": 41.32552,
               "longitude": -74.11235
           },
           {
               "latitude": 41.30111,
               "longitude": -74.13399
           },
           {
               "latitude": 41.21247,
               "longitude": -74.23388
           },
           ...
           {
               "latitude": 41.34374,
               "longitude": -73.97576
           }
       ]
   }
}

TravelTime API Response:

{
    "type": "FeatureCollection",
    "features": [
        {
            "type": "Feature",
            "geometry": {
                "type": "MultiPolygon",
                "coordinates": [
                    [
                        [
                            [
                                -74.66676814504899,
                                40.653876852826215
                            ],
                            [
                                -74.66441676905379,
                                40.65567800810095
                            ],
                            [
                                -74.66206539305858,
                                40.653876852826215
                            ],
                            [
                                -74.65971401706338,
                                40.65567800810095
                            ],
                            [
                                -74.65736264106818,
                                40.65567800810095
                            ],
                            ...
                            [
                                -73.28063199587632,
                                40.849302200134844
                            ]
                        ]
                    ]
                ]
            },
            "properties": {
                "search_id": "Example"
            }
        }
    ]
}

5. Error Handling

Both the TravelTIme API and the TomTom API use standard http status codes, such as 429 Too Many Requests 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
Structude	Nested `detailedError`	Nested `additional_info`
HTTP Status Code	Excluded from JSON body	Included in JSON body
Root Elements	`formatVersion` `detailedError`	`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 API Response:

{
   "formatVersion": "0.0.1",
   "detailedError": {
       "message": "Invalid value for timeBudgetInSec: 3600s",
       "code": "BAD_INPUT"
   }
}

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 Routing 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