Migration Guide: Mapbox Isochrone API to TravelTime Time Map Fast API

1. Introduction

This guide is aimed at helping a migration from the Mapbox Isochrone 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
Removing per minute usage limits
Longer travel times
Support for public transit
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	Mapbox API	TravelTime API
Maximum Isoline Size	1 hour	3 hours*
Sync / Async	Synchronous	Synchronous
Rate Limit	300 requests per minute	Unlimited
Transport Modes	Car, Pedestrian, Bicycle	Car, Pedestrian, Bicycle, Public Transit
Range Types	Travel time, Distance	Travel time, Distance*
Time of Day Configuration	Any time of day	Peak and Off Peak options
Response Formats	GeoJSON	JSON GeoJSON WKT
Pricing	Usage based	Fixed price, unlimited usage
Endpoint Playground	docs.mapbox.com/playground/isochrone/	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	Mapbox API	TravelTime API
Base URL	`api.mapbox.com/isochrone/v1`	`api.traveltimeapp.com/v4/time-map/fast`
API Version	Included in URL path (`/v1`)	Included in URL path (`/v4`)
Primary Request Type*	GET	POST*

*TravelTime API supports GET requests through the Time Map endpoint

Authentication

Feature	HERE API	TravelTime API
Authentication Method	`access_token` 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	N/A	`Accept: application/geo+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 Mapbox API uses GET requests, with parameters included in the query string, while the TravelTime API uses POST requests, with parameters included in the request body.

Feature	Mapbox API	TravelTime API
Batch Support	Limited to just multiple `range` values (max 4)	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	`/longitude,latitude`	`coords: { lat, lng }`
Transport Type	`/mapbox/driving` `/mapbox/driving-traffic` `/mapbox/walking` `/mapbox/cycling`	`transportation: { type:` `driving+ferry /` `cycling+ferry /` `walking+ferry /` `public_transport` `}`
Travel Time Configuration	`contours_minutes` (in minutes)	`travel_time` (in seconds)
Time of Day Configuration	`depart_at=2025-01-01T00:00:00Z`	`arrival_time_period: weekday_morning`
Shape Granularity	Controlled through: `denoise` (remove smaller separated polygons) `generalize` (control the granularity of the shape)	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.

Mapbox API Request:

curl -X GET
"https://api.mapbox.com/isochrone/v1/mapbox/driving/-73.99088,40.72511&contours_minutes=60?access_token={Your_Access_Token}"

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	Mapbox API	TravelTime API
Response Formats	GeoJSON	JSON GeoJSON WKT
Support for Holes	GeoJSON - handled natively	JSON - handled by `holes` arrays GeoJSON - handled natively WKT - handled natively
Support for Multiple Disconnected Polygons	GeoJSON - handled natively	JSON - handled by multiple `shell` arrays GeoJSON - handled natively WKT - handled natively
Isochrone Style Properties	Additional `properties` object contains details of the isochrone style (e.g fill and opacity)	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).

Mapbox API Response:

{
    "features": [
        {
            "properties": {
                "fill-opacity": 0.33,
                "fillColor": "#bf4040",
                "opacity": 0.33,
                "fill": "#bf4040",
                "fillOpacity": 0.33,
                "color": "#bf4040",
                "contour": 60,
                "metric": "time"
            },
            "geometry": {
                "coordinates": [
                    [
                        [
                            -73.99888,
                            41.325753
                        ],
                        [
                            -73.999804,
                            41.322034
                        ],
                        [
                            -74.005938,
                            41.322052
                        ],
                        [
                            -74.00688,
                            41.323584
                        ],
                        [
                            -74.016671,
                            41.322901
                        ],
                        ...
                    ]
                ],
                "type": "Polygon"
            },
            "type": "Feature"
        }
    ],
    "type": "FeatureCollection"
}

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 HERE API use standard http status codes, such as 401 Unauthorized and 500 Internal Server Error.

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

Feature	Mapbox API	TravelTime API
Structude	Flat (no nesting)	Nested `additional_info`
HTTP Status Code	Excluded from JSON body	Included in JSON body
Root Elements	`message` `code`	`http_status` `error_code` `description` `documentation_link` `additional_info`

Error Message Examples

The response examples below show the error response for an invalid query, with http error code 422.

Mapbox API Response:

{
   "message": "Invalid query param",
   "code": "InvalidInput"
}

TravelTime API Response:

{
   "http_status": 422,
   "error_code": 2,
   "description": "Invalid request json",
   "documentation_link": "https://docs.traveltime.com/reference/error-codes",
   "additional_info": {
       "obj.arrival_searches.one_to_many[0].transportation.type": [
           "Path missing"
       ]
   }
}

6. Next Steps

If you are looking to migrate from using the Mapbox Isochrone 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