Travel Time Matrix

Getting a TravelTime API key

• If you don’t already have a TravelTime API key, then you can get a free key by creating an account here
• Once you’ve verified your email and logged in, you’ll land on your new TravelTime account dashboard
• Here you can find your API credentials that you will need to use when making any requests to the TravelTime API

Making a Request

The simplest Travel Time Matrix endpoint to use is the /v4/time-filter/fast endpoint.

• A single Request is made up of 1 or more Searches (up to a maximum of 10)
• Each Search is either a one-to-many or a many-to-one calculation
• Each Search can include a maximum of 100,000 locations

Headers

• Request type - POST
• Host - api.traveltimeapp.com
• Endpoint - /v4/time-filter/fast
• Authentication - Application-Id, Api-Key

Required parameters

• locations - an array containing the IDs and lat-long coordinates of the locations to be used in the travel time calculations
• arrival_time_period - weekday_morning reflects the typical travel times at 8-9am (in the local time zone where the locations are situated
• travel_time - used to filter the locations into those that are reachable and unreachable within the chosen travel time (up to 3 hours)
• transportation type - possible values are public_transport, walking+ferry, cycling+ferry, driving+ferry, driving+public_transport
• properties - the data point(s) to be calculated for each location - typically travel_time and/or distance

A full list of available parameters, including optional ones, can be found here.

Example

Click Try it now to open the endpoint Developer Playground and execute the request.

{
   "arrival_searches": {
          "one_to_many": [
       {
         "id": "Example Search",
         "departure_location_id": "Origin",
         "arrival_location_ids": [
           "Destination 1",
           "Destination 2",
           "Destination 3"
         ],
         "transportation": {
             "type": "driving"
         },
         "travel_time": 10800,
         "arrival_time_period": "weekday_morning",
         "properties": [
           "travel_time",
           "distance"
         ]
       }
     ]
   },
     "locations": [
     {
       "id": "Origin",
       "coords": {
         "lat": 54.238911,
         "lng": -0.397567
       }
     },
     {
       "id": "Destination 1",
       "coords": {
         "lat": 54.24424722,
         "lng": -0.407544543
       }
     },
         {
       "id": "Destination 2",
       "coords": {
         "lat": 54.35384,
         "lng": -0.434984
       }
     },
         {
       "id": "Destination 3",
       "coords": {
         "lat": 53.99283,
         "lng": -0.519234
       }
     }
   ]
 }

Example formatted as a Curl 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 '{
   "arrival_searches": {
          "one_to_many": [
       {
         "id": "Example Search",
         "departure_location_id": "Origin",
         "arrival_location_ids": [
           "Destination 1",
           "Destination 2",
           "Destination 3"
         ],
         "transportation": {
             "type": "driving"
         },
         "travel_time": 10800,
         "arrival_time_period": "weekday_morning",
         "properties": [
           "travel_time",
           "distance"
         ]
       }
     ]
   },
     "locations": [
     {
       "id": "Origin",
       "coords": {
         "lat": 54.238911,
         "lng": -0.397567
       }
     },
     {
       "id": "Destination 1",
       "coords": {
         "lat": 54.24424722,
         "lng": -0.407544543
       }
     },
         {
       "id": "Destination 2",
       "coords": {
         "lat": 54.35384,
         "lng": -0.434984
       }
     },
         {
       "id": "Destination 3",
       "coords": {
         "lat": 53.99283,
         "lng": -0.519234
       }
     }
   ]
 }'

Interpreting the Response

Successful requests

A successful request will return a response that includes:

• The ID of the search
• The ID of each location within the search
• The requested Properties for each location - the travel_time unit is seconds, the distance unit is metres
• Any Unreachable locations - no Properties will be returned for these locations

{
   "results": [
       {
           "search_id": "Example Search",
           "locations": [
               {
                   "id": "Destination 1",
                   "properties": {
                       "travel_time": 311,
                       "distance": 1629
                   }
               },
               {
                   "id": "Destination 2",
                   "properties": {
                       "travel_time": 2050,
                       "distance": 15450
                   }
               },
               {
                   "id": "Destination 3",
                   "properties": {
                       "travel_time": 3121,
                       "distance": 38065
                   }
               }
           ],
           "unreachable": []
       }
   ]
}

To calculate a matrix with multiple origins and multiple destinations, simply add multiple Searches into the request.

Unsuccessful requests

An unsuccessful request will return an error message. For example, if invalid API credentials are used, the following error is returned.

{
  "http_status": 401,
  "error_code": 10,
  "description": "Application Id or Api Key is invalid",
  "documentation_link": "http://docs.traveltimeplatform.com/reference/error-codes",
  "additional_info": {}
}

A full list of error codes can be found here.

Alternative endpoints

If this endpoint doesn’t meet your requirements, then there are two other Matrix endpoints to consider.

Time Filter

The /v4/time-filter endpoint has more configurable parameters, and is available in all 234 countries listed here. But it comes with the limitations of smaller request size (max 2,000 locations per search) and slower response times (up to 5-10x slower for complex requests).

Protobuf

The Protobuf endpoint has even lower response times, and accepts up to 200,000 locations per search. It is best accessed through one of our SDKs or database plugins.

You can find a full comparison of the available matrix endpoints here.