Routes
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
- Generating a Route 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
- 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:
Routes Request
{
"locations": [
{
"id": "Home",
"coords": {
"lat": 51.5815890,
"lng": -0.0775871
}
},
{
"id": "Office",
"coords": {
"lat": 51.511933,
"lng": -0.1277888
}
}
],
"arrival_searches": [
{
"id": "Morning Commute",
"arrival_location_id": "Office",
"departure_location_ids": [
"Home"
],
"arrival_time": "2021-09-28T09:00:00Z",
"properties": ["route"],
"transportation": {
"type": "driving"
}
}
]
}- To make the request, copy the following Curl request
Curl request
curl -X POST https://api.traveltimeapp.com/v4/routes \
-H 'Content-Type: application/json' \
-H 'X-Application-Id: YOUR_APP_ID' \
-H 'X-Api-Key: YOUR_APP_KEY' \
-d '{
"locations": [
{
"id": "Home",
"coords": {
"lat": 51.5815890,
"lng": -0.0775871
}
},
{
"id": "Office",
"coords": {
"lat": 51.511933,
"lng": -0.1277888
}
}
],
"arrival_searches": [
{
"id": "Morning Commute",
"arrival_location_id": "Office",
"departure_location_ids": [
"Home"
],
"arrival_time": "2021-09-28T09:00:00Z",
"properties": ["route"],
"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
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
- Route Parts - when the ‘route’ property is requested, individual parts of the route will be listed one by one, each including details such as the mode of transport being used, the coordinates of the route, and the directions (e.g ‘Drive 44 metres along Elizabeth road’)
- Any Unreachable locations - no Properties will be returned for these locations
Routes Response
{
"results": [
{
"search_id": "Morning Commute",
"locations": [
{
"id": "Home",
"properties": [
{
"route": {
"departure_time": "2021-09-28T09:01:46+01:00",
"arrival_time": "2021-09-28T10:00:00+01:00",
"parts": [
{
"id": 0,
"type": "start_end",
"mode": "walk",
"directions": "Start your journey 32 meters south",
"distance": 32,
"travel_time": 22,
"coords": [
{
"lat": 51.581589,
"lng": -0.0775871
},
{
"lat": 51.58130289999993,
"lng": -0.07751859999999677
}
],
"direction": "south"
},
{
"id": 1,
"type": "road",
"mode": "car",
"directions": "Drive 44 meters along Elizabeth Road",
"distance": 44,
"travel_time": 14,
"coords": [
{
"lat": 51.58130289999993,
"lng": -0.07751859999999677
},
{
"lat": 51.580975999999936,
"lng": -0.07714029999999678
}
],
"road": "Elizabeth Road"
},
{
"id": 2,
"type": "road",
"mode": "car",
"directions": "Turn right onto Seven Sisters Road (A503) and drive 2637 meters",
"distance": 2637,
"travel_time": 719,
"coords": [
{
"lat": 51.580975999999936,
"lng": -0.07714029999999678
},
{
"lat": 51.58071970000015,
"lng": -0.07773999999999763
},
...
{
"lat": 51.56470679999972,
"lng": -0.1044903999999928
}
],
"road": "Seven Sisters Road (A503)",
"turn": "right"
},
{
"id": 3,
"type": "road",
"mode": "car",
"directions": "Turn left onto Blackstock Road (A1201) and drive 879 meters",
"distance": 879,
"travel_time": 333,
"coords": [
{
"lat": 51.56470679999972,
"lng": -0.1044903999999928
},
{
"lat": 51.564590200000296,
"lng": -0.10427649999999995
},
...
{
"lat": 51.5581603,
"lng": -0.0985288999999997
}
],
"road": "Blackstock Road (A1201)",
"turn": "left"
},
{
"id": 4,
"type": "road",
"mode": "car",
"directions": "Continue onto Highbury Park (A1201) for 554 meters",
"distance": 554,
"travel_time": 147,
"coords": [
{
"lat": 51.5581603,
"lng": -0.0985288999999997
},
{
"lat": 51.557955500000105,
"lng": -0.09849139999999298
},
...
{
"lat": 51.55313440000014,
"lng": -0.09840830000001118
}
],
"road": "Highbury Park (A1201)",
"turn": "straight"
},
{
"id": 5,
"type": "road",
"mode": "car",
"directions": "Continue onto Highbury Grove (A1201) for 699 meters",
"distance": 699,
"travel_time": 224,
"coords": [
{
"lat": 51.55313440000014,
"lng": -0.09840830000001118
},
{
"lat": 51.55285400000011,
"lng": -0.09837679999999298
},
...
{
"lat": 51.54675819999997,
"lng": -0.09855170000000069
}
],
"road": "Highbury Grove (A1201)",
"turn": "straight"
},
{
"id": 6,
"type": "road",
"mode": "car",
"directions": "Turn right onto St. Paul's Road (A1199) and drive 257 meters",
"distance": 257,
"travel_time": 89,
"coords": [
{
"lat": 51.54675819999997,
"lng": -0.09855170000000069
},
{
"lat": 51.54674800000026,
"lng": -0.09859180000000209
},
...
{
"lat": 51.5460895000001,
"lng": -0.10217619999997717
}
],
"road": "St. Paul's Road (A1199)",
"turn": "right"
},
{
"id": 7,
"type": "road",
"mode": "car",
"directions": "Slight left onto Highbury Corner (A1) and drive 119 meters",
"distance": 119,
"travel_time": 81,
"coords": [
{
"lat": 51.5460895000001,
"lng": -0.10217619999997717
},
{
"lat": 51.54606959999968,
"lng": -0.1021934999999983
},
...
{
"lat": 51.54552180000004,
"lng": -0.10313049999999002
}
],
"road": "Highbury Corner (A1)",
"turn": "slight_left"
},
{
"id": 8,
"type": "road",
"mode": "car",
"directions": "Slight left onto Upper Street (A1) and drive 1438 meters",
"distance": 1438,
"travel_time": 489,
"coords": [
{
"lat": 51.54552180000004,
"lng": -0.10313049999999002
},
{
"lat": 51.54549770000004,
"lng": -0.10317449999999002
},
...
{
"lat": 51.53299799999994,
"lng": -0.10611410000000035
}
],
"road": "Upper Street (A1)",
"turn": "slight_left"
},
{
"id": 9,
"type": "road",
"mode": "car",
"directions": "Turn left onto Islington High Street (A1) and drive 118 meters",
"distance": 118,
"travel_time": 46,
"coords": [
{
"lat": 51.53299799999994,
"lng": -0.10611410000000035
},
{
"lat": 51.53292899999988,
"lng": -0.10613809999999148
},
...
{
"lat": 51.53190879999996,
"lng": -0.10626749999999725
}
],
"road": "Islington High Street (A1)",
"turn": "left"
},
{
"id": 10,
"type": "road",
"mode": "car",
"directions": "Slight left onto St. John Street (A401) and drive 150 meters",
"distance": 150,
"travel_time": 68,
"coords": [
{
"lat": 51.53190879999996,
"lng": -0.10626749999999725
},
{
"lat": 51.531772899999936,
"lng": -0.10622779999999832
},
{
...
{
"lat": 51.53056549999997,
"lng": -0.10578349999999737
}
],
"road": "St. John Street (A401)",
"turn": "slight_left"
},
{
"id": 11,
"type": "road",
"mode": "car",
"directions": "Turn right onto Chadwell Street and drive 30 meters",
"distance": 30,
"travel_time": 10,
"coords": [
{
"lat": 51.53056549999997,
"lng": -0.10578349999999737
},
{
"lat": 51.53051370000047,
"lng": -0.10598349999999705
},
{
"lat": 51.53051640000047,
"lng": -0.10600999999999705
},
{
"lat": 51.530502299999974,
"lng": -0.10615509999999714
},
{
"lat": 51.530486899999964,
"lng": -0.10621209999999774
}
],
"road": "Chadwell Street",
"turn": "right"
},
{
"id": 12,
"type": "road",
"mode": "car",
"directions": "Turn left onto Arlington Way and drive 186 meters",
"distance": 186,
"travel_time": 75,
"coords": [
{
"lat": 51.530486899999964,
"lng": -0.10621209999999774
},
{
"lat": 51.53042750000046,
"lng": -0.10621629999999738
},
...
{
"lat": 51.52885250000046,
"lng": -0.10636899999999738
}
],
"road": "Arlington Way",
"turn": "left"
},
{
"id": 13,
"type": "road",
"mode": "car",
"directions": "Turn right onto Rosebery Avenue (A401) and drive 906 meters",
"distance": 906,
"travel_time": 318,
"coords": [
{
"lat": 51.52885250000046,
"lng": -0.10636899999999738
},
{
"lat": 51.52883430000025,
"lng": -0.10638899999999618
},
...
{
"lat": 51.52170459999991,
"lng": -0.11246179999999238
}
],
"road": "Rosebery Avenue (A401)",
"turn": "right"
},
{
"id": 14,
"type": "road",
"mode": "car",
"directions": "Turn right onto Clerkenwell Road (A401) and drive 61 meters",
"distance": 61,
"travel_time": 48,
"coords": [
{
"lat": 51.52170459999991,
"lng": -0.11246179999999238
},
{
"lat": 51.52167539999991,
"lng": -0.11261719999999238
},
...
{
"lat": 51.52151369999997,
"lng": -0.11331999999999999
}
],
"road": "Clerkenwell Road (A401)",
"turn": "right"
},
{
"id": 15,
"type": "road",
"mode": "car",
"directions": "Continue onto Theobalds Road (A401) for 488 meters",
"distance": 488,
"travel_time": 190,
"coords": [
{
"lat": 51.52151369999997,
"lng": -0.11331999999999999
},
{
"lat": 51.5214838,
"lng": -0.11344029999999994
},
...
{
"lat": 51.51967059999997,
"lng": -0.11986929999999726
}
],
"road": "Theobalds Road (A401)",
"turn": "straight"
},
{
"id": 16,
"type": "road",
"mode": "car",
"directions": "Turn left onto Drake Street (A401) and drive 36 meters",
"distance": 36,
"travel_time": 34,
"coords": [
{
"lat": 51.51967059999997,
"lng": -0.11986929999999726
},
{
"lat": 51.51963590000023,
"lng": -0.11986359999998838
},
...
{
"lat": 51.51933069999981,
"lng": -0.1198791999999948
}
],
"road": "Drake Street (A401)",
"turn": "left"
},
{
"id": 17,
"type": "road",
"mode": "car",
"directions": "Slight left onto Drake Street (A40) and drive 20 meters",
"distance": 20,
"travel_time": 5,
"coords": [
{
"lat": 51.51933069999981,
"lng": -0.1198791999999948
},
{
"lat": 51.51915799999982,
"lng": -0.11975850000000032
}
],
"road": "Drake Street (A40)",
"turn": "slight_left"
},
{
"id": 18,
"type": "road",
"mode": "car",
"directions": "Continue onto Red Lion Square (A40) for 48 meters",
"distance": 48,
"travel_time": 11,
"coords": [
{
"lat": 51.51915799999982,
"lng": -0.11975850000000032
},
{
"lat": 51.518941199999965,
"lng": -0.11960930000000217
},
{
"lat": 51.518757799999925,
"lng": -0.11947459999999303
}
],
"road": "Red Lion Square (A40)",
"turn": "straight"
},
{
"id": 19,
"type": "road",
"mode": "car",
"directions": "Continue onto Procter Street (A40) for 118 meters",
"distance": 118,
"travel_time": 49,
"coords": [
{
"lat": 51.518757799999925,
"lng": -0.11947459999999303
},
{
"lat": 51.51862630000009,
"lng": -0.11938419999999339
},
...
{
"lat": 51.517705699999915,
"lng": -0.11917809999999737
}
],
"road": "Procter Street (A40)",
"turn": "straight"
},
{
"id": 20,
"type": "road",
"mode": "car",
"directions": "Slight right onto High Holborn (A40) and drive 569 meters",
"distance": 569,
"travel_time": 304,
"coords": [
{
"lat": 51.517705699999915,
"lng": -0.11917809999999737
},
{
"lat": 51.517682400000425,
"lng": -0.11960099999998319
},
...
{
"lat": 51.5156788000001,
"lng": -0.12667710000000998
}
],
"road": "High Holborn (A40)",
"turn": "slight_right"
},
{
"id": 21,
"type": "road",
"mode": "car",
"directions": "Turn left onto Shaftesbury Avenue (A401) and drive 296 meters",
"distance": 296,
"travel_time": 98,
"coords": [
{
"lat": 51.5156788000001,
"lng": -0.12667710000000998
},
...
{
"lat": 51.513406999999916,
"lng": -0.12892390000000345
}
],
"road": "Shaftesbury Avenue (A401)",
"turn": "left"
},
{
"id": 22,
"type": "road",
"mode": "car",
"directions": "Turn left onto West Street and drive 123 meters",
"distance": 123,
"travel_time": 74,
"coords": [
{
"lat": 51.513406999999916,
"lng": -0.12892390000000345
},
{
"lat": 51.513261900000174,
"lng": -0.12858399999999784
},
...
{
"lat": 51.512662300000166,
"lng": -0.12756880000000592
}
],
"road": "West Street",
"turn": "left"
},
{
"id": 23,
"type": "road",
"mode": "car",
"directions": "Turn right and drive 62 meters",
"distance": 62,
"travel_time": 21,
"coords": [
{
"lat": 51.512662300000166,
"lng": -0.12756880000000592
},
{
"lat": 51.51265680000009,
"lng": -0.12757279999999457
},
...
{
"lat": 51.51224440000021,
"lng": -0.12792519999999702
}
],
"turn": "right"
},
{
"id": 24,
"type": "start_end",
"mode": "walk",
"directions": "Your destination is 35 meters southeast",
"distance": 35,
"travel_time": 25,
"coords": [
{
"lat": 51.51224440000021,
"lng": -0.12792519999999702
},
{
"lat": 51.511933,
"lng": -0.1277888
}
],
"direction": "southeast"
}
]
}
}
]
}
],
"unreachable": []
}
]
}- Note that the Routes API is best used for calculating turn-by-turn directions and visualisations of A to B journeys. If you are simply looking to calculate journey times or distances, then try the Distance Matrix API instead.
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