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.
- Exceptional performance
- Additional public transit, cycling, and walking modes
- More detailed isochrones
- Fixed cost and unlimited usage, instead of transactional pricing
- Permissive caching policy
The table below covers the main features of the two services.
| 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
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.
| 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
| 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: gzipContent-Encoding: gzipContent-Type: application/jsonTracking-ID | Accept: application/json(used to adjust the response format - e.g geoJSON, JSON, or WKT) |
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.
| 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) |
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.
curl -X GET
"https://api.tomtom.com/routing/1/calculateReachableRange/40.72511,-73.99088/json?timeBudgetInSec=3600&travelMode=car&key={Your_API_Key}"
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"
}
}
]
}
}'
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.
| 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 |
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).
{
"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
}
]
}
}
{
"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"
}
}
]
}
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.
| TomTom API | TravelTime API | |
|---|---|---|
| Structude | Nested detailedError | Nested additional_info |
| HTTP Status Code | Excluded from JSON body | Included in JSON body |
| Root Elements | formatVersiondetailedError | http_statuserror_codedescriptiondocumentation_linkadditional_info |
The response examples below show the error response for a poorly formatted JSON request, with http error code 400.
{
"formatVersion": "0.0.1",
"detailedError": {
"message": "Invalid value for timeBudgetInSec: 3600s",
"code": "BAD_INPUT"
}
}
{
"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"
]
}
}
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.
Sign upTo help you get up and running, check out some of the links to more resources below.