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

The simplest way to create a Distance Matrix is using the Time Filter endpoint
Generating a Distance Matrix requires a single POST request
The required parameters are:
- IDs - unique identifiers for the departure and arrival locations
- Latitude and longitude coordinates - these set the departure and arrival locations
- Transportation type - the most popular are
driving
,public_transport
,walking
, andcycling
, 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:
{
"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"
],
"departure_time": "2021-09-21T08:00:00Z",
"travel_time": 3600,
"properties": [
"travel_time",
"distance"
],
"transportation": {
"type": "driving"
}
}
]
}
- 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: YOUR_APP_ID' \
-H 'X-Api-Key: YOUR_APP_KEY' \
-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"
],
"departure_time": "2021-09-21T08:00:00Z",
"travel_time": 3600,
"properties": [
"travel_time",
"distance"
],
"transportation": {
"type": "driving"
}
}
]
}'
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
- 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, thedistance
unit is metresAny Unreachable locations - no Properties will be returned for these locations
{
"results": [
{
"search_id": "One-to-many Matrix",
"locations": [
{
"id": "London Eye",
"properties": [
{
"travel_time": 670,
"distance": 2504
}
]
},
{
"id": "Wimbledon Tennis Club",
"properties": [
{
"travel_time": 3229,
"distance": 14008
}
]
},
{
"id": "Hyde Park",
"properties": [
{
"travel_time": 1037,
"distance": 3426
}
]
},
{
"id": "Houses of Parliament",
"properties": [
{
"travel_time": 785,
"distance": 1802
}
]
}
],
"unreachable": [
]
}
]
}
- 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
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
If you are looking to create much larger Distance Matrices, or require even lower response times, there are two alternative endpoints you can use:
- Time Filter Fast (JSON) - a stripped down version of the Time Filter (JSON) endpoint that allows up to 100,000 locations per request
- Time Filter Fast (Protobuf) - our highest performance endpoint allowing up to 200,000 elements per request in under 150ms