- 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 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
- Request type - POST
- Host - api.traveltimeapp.com
- Endpoint - /v4/time-filter/fast
- Authentication - Application-Id, Api-Key
- 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/ordistance
A full list of available parameters, including optional ones, can be found here.
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
}
}
]
}'
If you aren’t logged in then you’ll need to manually enter your own Application ID and API Key in place of the placeholders
This endpoint is available in the 32 countries listed here. If you require support for another country then see the Alternative Travel Time Matrix Endpoints section at the bottom of this page.
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 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.
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 this endpoint doesn’t meet your requirements, then there are two other Matrix endpoints to consider.
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).
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.