Travel Time Matrix
Getting a TravelTime API key
If you don’t already have a TravelTime API key, then you can sign up for one here
Look out for an email from support@traveltime.com (if you don’t receive anything within a couple of minutes, try checking your spam folder)

- The email will include your API credentials, so save these somewhere easily accessible

- You’ll also find a password which you will need in order to log in to see your API usage in the future, so note this down too

Making a Request
Generating a Distance Matrix requires a single POST request
The required parameters are:
ID - a unique identifier for the isochrone used as a reference in the subsequent API response
Latitude and longitude coordinates - these set the departure or arrival location
Transportation type - the most popular are ‘driving’, ‘public_transport’, ‘walking’, and ‘cycling’, but a full list can be found here
Departure or Arrival time - this must be in extended ISO-8601 format, for example 2021-09-27T08:00:00Z
Travel time- the maximum journey time in seconds (any journeys beyond this will be returned as ‘Unreachable’)
Properties- the desired properties to be returned for each journey, where the options are ‘route’, ‘travel_time’, ‘distance’, ‘fares’
As a simple JSON request body, this looks like the following example:
- To make the request, copy the following Curl request
curl -X POST \
https://api.traveltimeapp.com/v4/time-filter \
-H 'Content-Type: application/json' \
-H 'X-Application-Id: XXXXXXXX' \
-H 'X-Api-Key: XXXXXXXX' \
-d '{
"locations": [
{
"id": "TravelTime HQ",
"coords": {
"lat": 51.51198245486377,
"lng": -0.1278277598563
}
},
{
"id": "Hyde Park",
"coords": {
"lat": 51.503120589264064,
"lng": -0.15282095066100
}
},
{
"id": "London Eye",
"coords": {
"lat": 51.503341807681544,
"lng": -0.11952824596429
}
},
{
"id": "Houses of Parliament",
"coords": {
"lat": 51.499580735687275,
"lng": -0.12479520475271223
}
},
{
"id": "Wimbledon Tennis Club",
"coords": {
"lat": 51.43540206193277,
"lng": -0.2140336019409371
}
}
],
"departure_searches": [
{
"id": "One-to-many Matrix",
"departure_location_id": "TravelTime HQ",
"arrival_location_ids": [
"Hyde Park",
"London Eye",
"Houses of Parliament",
"Wimbledon Tennis Club"
],
"transportation": {
"type": "driving"
},
"departure_time": "2021-09-21T08:00:00Z",
"travel_time": 3600,
"properties": [
"travel_time",
"distance"
]
}
]
}'
Note: you’ll need to enter your own Application ID and API Key in place of the placeholders
- A full list of available parameters, including optional ones, can be found here
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": "One-to-many Matrix",
"locations": [
{
"id": "London Eye",
"properties": [
{
"travel_time": 1004,
"distance": 2337
}
]
},
{
"id": "Hyde Park",
"properties": [
{
"travel_time": 1324,
"distance": 3172
}
]
},
{
"id": "Houses of Parliament",
"properties": [
{
"travel_time": 904,
"distance": 1775
}
]
}
],
"unreachable": [
"Wimbledon Tennis Club"
]
}
]
}
- To calculate a matrix with multiple origins and multiple destinations, simply add multiple Searches into the request. Each of these Searches can then include up to 2,000 Locations
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