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

1. Introduction

This guide is aimed at helping a migration from the Matrix API from Mapbox, 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.

Why migrate to TravelTime?

Larger matrices (10x100,000 vs 25x25)
Support for public transit (as well as driving, cycling, 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	Mapbox API	TravelTime API
Maximum Matrix Size	25 x 25	10 x 100,000
Sync / Async	Synchronous	Synchronous
Transport Modes	Car, Pedestrian, Bicycle	Car, Pedestrian, Bicycle, Public Transit
Calculated Properties	Travel time, Distance	Travel time, Distance
Time of Day Configuration	Only in BETA	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	Paid	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	Mapbox API	TravelTime API
Base URL	`api.mapbox.com/directions-matrix/v1`	`api.traveltimeapp.com/v4/time-filter/fast`
API Version	Included in URL path (`/v1`)	Included in URL path (`/v4`)
Request Type	GET	POST*

*TravelTime API supports GET requests through the Travel Time Matrix endpoint

Authentication

Feature	Mapbox 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}`

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
Search Structure	By default, calculates a square matrix with `coordinates` as origins and destinations `destinations` and `sources` used to build non-square matrices	Individual `one-to-many` or `many-to-one` searches grouped in one request
Location Format	Semi-colon separated list of coordinates	`locations` array with IDs
Configuration	Via additional query string parameters	Via parameters within the request body, which can differ between searches
Transport Type	`/mapbox/driving` `/mapbox/driving-traffic` `/mapbox/walking` `/mapbox/cycling`	`transportation: { type:` `driving+ferry /` `cycling+ferry /` `walking+ferry /` `public_transport` `}`
Time of Day Configuration	`depart_at=2025-01-01T00:00:00Z` (BETA)	`arrival_time_period: weekday_morning`
Result Properties	Requested via `annotations` string	Requested via `properties` array

Request Examples

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

Mapbox API Request:

curl -X GET "https://api.mapbox.com/directions-matrix/v1/mapbox/driving/-0.293897,51.532131;-0.435683,51.871461;-1.258321,51.749232;-1.011401,50.899630?access_token={Your_Access_Token}&annotations=duration,distance&destinations=2;3&sources=0;1"

TravelTime API Request:

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
Matrix Format	Matrices structured as two separate arrays of arrays - `durations` and `distances`	Travel times and distances structured as a list of results per origin (`search_id`)
Unsuccessful Results	Recorded with `null` values in `durations` / `distances` arrays	Nested arrays grouped by individual searches
Entry Identification	Requires mapping between source and destination indexes	Uses string IDs (`search_id`, `id`)
Distance Unit	`Metres`	`Metres`
Travel Time Unit	`Seconds`	`Seconds`
Locations Metadata	Arrays of waypoint objects (`sources` / `destinations`) with snapping details	N/A

Response Examples

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

Mapbox API Response:

{
   "code": "Ok",
   "distances": [
       [
           82457.3,
           117450.3
       ],
       [
           109461.1,
           144013.2
       ]
   ],
   "destinations": [
       {
           "distance": 22.279985065,
           "name": "Cambridge Terrace",
           "location": [
               -1.258305,
               51.749032
           ]
       },
       {
           "distance": 46.37681243,
           "name": "Cotwell Avenue",
           "location": [
               -1.01079,
               50.899474
           ]
       }
   ],
   "durations": [
       [
           4644.4,
           6167.4
       ],
       [
           5855.7,
           7321.4
       ]
   ],
   "sources": [
       {
           "distance": 5.684801986,
           "name": "",
           "location": [
               -0.293892,
               51.532182
           ]
       },
       {
           "distance": 7.156707458,
           "name": "",
           "location": [
               -0.435768,
               51.871498
           ]
       }
   ]
}

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 Mapbox 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:

{
   "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 Mapbox 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