JSON API /v4/time-filterTravel Time Matrix (Time Filter)
Create a distance matrix with the travel times and distances between thousands of locations in one go.
Supports two HTTP request types:
- GET - for simple requests using basic parameters only
- POST - for more complex requests using advanced parameters
With both request types, to create a many-to-many matrix you will need to use multiple searches.
For example given three points A, B, C you would need three arrival searches - one for each point.
- A -> { B, C }
- B -> { A, C }
- C -> { A, B }
Access URL: https://api.traveltimeapp.com/v4/time-filter
POST Request
A POST request should be used for any of the following use cases:
- Using advanced parameters not available in the GET request
- Calculating a many-to-many matrix
The access URL is the same as the GET request format, but the differences are:
- Authentication is included in the request Headers
- Parameters are included in the request Body
Access URL: https://api.traveltimeapp.com/v4/time-filter
Request Body
array[object]
Define your locations to use later in departure_searches or arrival_searches.
array[object]
Searches based on a departure time. Leave the departure location no earlier than the given time.
Specify a single departure location and multiple arrival locations in each search (one-to-many).
You can define a maximum of 10 searches per request.
string
Used to identify each search in the results array. Must be unique among all searches.
array[object]
The id of the location to depart from. Must reference an id from the locations array.
array[object]
The ids of the locations to arrive at. Must reference ids from the locations array.
You can define a maximum of 2000 location ids.
date in extended ISO-8601 format
Leave departure location at no earlier than given time. In ISO 8601 format. For example:
2023-02-06T14:00:00Z (representing UTC)
2023-02-06T14:00:00-05:00 (representing New York on Standard Time: UTC-05:00)
integer
Maximum journey time (in seconds). Maximum value is 14400 (4 hours) as standard. To discuss increasing this, please contact sales@traveltime.com.
array[string]
Properties to be returned for each arrival location. Possible values:
travel_time,
route,
distance (driving, walking and cycling modes only),
distance_breakdown (driving, walking and cycling modes only),
fares (UK only. public_transport, coach, bus, train, and driving+train modes only)
Transportation mode and related parameters. type is a mandatory field, but all other fields are optional and default values are used if not specified.
cycling, driving, driving+train (only in Great Britain), public_transport, walking, coach, bus, train, ferry, driving+ferry, cycling+ferry or cycling+public_transport (only in Netherlands).
integer | optional
Maximum time (in seconds) allowed for walking at the start and end of a public transport journey. i.e:
- the maximum walking time from the origin to the first stop/station, and
- the maximum walking time from the final stop/station to the destination
These limits are independent and not cumulative. They only apply to the first and last walking legs of the journey - all walking times between public transport legs are limited to 600s (10 minutes) each.
The default value is 900.
Cannot be higher than travel_time.
Used in public_transport, coach, bus, train, driving+train and cycling+public_transport transportation modes.
integer | optional
Time in seconds needed to board public transportation vehicle.
Default is 0.
Cannot be higher than travel_time.
Used in public_transport, coach, bus, train, driving+train and cycling+public_transport transportation modes.
integer | optional
Maximum time (in seconds) allowed for driving from the origin to the train station.
Default value is 1800.
Cannot be higher than travel_time.
Used only in driving+train transportation mode.
integer | optional
Maximum time (in seconds) allowed for cycling (including any ferry transfers) from from the origin to the first stop/station.
Default value is 900.
Cannot be higher than travel_time.
Used only in cycling+public_transport transportation mode.
integer | optional
Time in seconds required to park a car or a bicycle.
Default value is 300.
Cannot be higher than travel_time.
Used in driving+train and cycling+public_transport transportation modes.
integer | optional
Time in seconds required to board a ferry.
Default value is 0.
Cannot be higher than travel_time.
Used in public_transport, ferry, driving+ferry, cycling+ferry and cycling+public_transport transportation modes. For public_transport mode, pt_change_delay is used instead.
boolean | optional
If set to true, the crossing of country borders is disabled. Only available with the driving transportation mode, and is enabled by default (false).
object | optional
Upper limit for the number of changes between public transit legs in a journey.
Used in public_transport, coach, bus, train, driving+train and cycling+public_transport transportation modes. For other modes the max_changes parameter is ignored.
Enable transit leg change limit?
Maximum number of changes between transit legs in a journey. Must be at least 0.
object | optional
When enabled, range adds a departure window to the departure time, and results are returned for any journeys that depart during this window.
In the results array, the properties of these multiple alternative results are sorted by travel_time in ascending order.
Disabled by default.
Used in public_transport, coach, bus, train, driving+train and cycling+public_transport transportation modes. For other modes the parameter is ignored.
boolean
Enable range search?
integer
Maximum number of results to return for each arrival location.
Maximum value is 5.
integer
The width of the range window (in seconds).
The window is applied 'forwards' from the departure time. For example, with a departure_time of 9am and a range width of 1 hour, the results with the shortest journey time departing between 9am and 10am will be returned.
If no results are found that fall within this departure window, a single result will be returned which has the earliest departure time after the departure window.
Maximum value is 43200 (12 hours).
array[object]
Searches based on an arrival time. Arrive at the location no earlier than the given time.
Specify multiple departure locations and one arrival location in each search (many-to-one).
You can define a maximum of 10 searches per request.
string
Used to identify each search in the results array. Must be unique among all searches.
array[object]
The ids of the locations to depart from. Must reference ids from the locations array.
You can define a maximum of 2000 location ids.
array[object]
The id of the location to arrive at. Must reference an id from the locations array.
date in extended ISO-8601 format
Be at arrival location at no later than given time. In ISO 8601 format. For example:
2023-02-06T14:00:00Z (representing UTC)
2023-02-06T14:00:00-05:00 (representing New York on Standard Time: UTC-05:00)
integer
Maximum journey time (in seconds). Maximum value is 14400 (4 hours) as standard. To discuss increasing this, please contact sales@traveltime.com.
array[string]
Properties to be returned for each arrival location. Possible values:
travel_time,
route,
distance (driving, walking and cycling modes only),
distance_breakdown (driving, walking and cycling modes only),
fares (UK only. public_transport, coach, bus, train, and driving+train modes only)
Transportation mode and related parameters. type is a mandatory field, but all other fields are optional and default values are used if not specified.
cycling, driving, driving+train (only in Great Britain), public_transport, walking, coach, bus, train, ferry, driving+ferry, cycling+ferry or cycling+public_transport (only in Netherlands).
integer | optional
Maximum time (in seconds) allowed for walking at the start and end of a public transport journey. i.e:
- the maximum walking time from the origin to the first stop/station, and
- the maximum walking time from the final stop/station to the destination
These limits are independent and not cumulative. They only apply to the first and last walking legs of the journey - all walking times between public transport legs are limited to 600s (10 minutes) each.
The default value is 900.
Cannot be higher than travel_time.
Used in public_transport, coach, bus, train, driving+train and cycling+public_transport transportation modes.
integer | optional
Time in seconds needed to board public transportation vehicle.
Default is 0.
Cannot be higher than travel_time.
Used in public_transport, coach, bus, train, driving+train and cycling+public_transport transportation modes.
integer | optional
Maximum time (in seconds) allowed for driving from the origin to the train station.
Default value is 1800.
Cannot be higher than travel_time.
Used only in driving+train transportation mode.
integer | optional
Maximum time (in seconds) allowed for cycling (including any ferry transfers) from from the origin to the first stop/station.
Default value is 900.
Cannot be higher than travel_time.
Used only in cycling+public_transport transportation mode.
integer | optional
Time in seconds required to park a car or a bicycle.
Default value is 300.
Cannot be higher than travel_time.
Used in driving+train and cycling+public_transport transportation modes.
integer | optional
Time in seconds required to board a ferry.
Default value is 0.
Cannot be higher than travel_time.
Used in public_transport, ferry, driving+ferry, cycling+ferry and cycling+public_transport transportation modes. For public_transport mode, pt_change_delay is used instead.
boolean | optional
If set to true, the crossing of country borders is disabled. Only available with the driving transportation mode, and is enabled by default (false).
object | optional
Upper limit for the number of changes between public transit legs in a journey.
Used in public_transport, coach, bus, train, driving+train and cycling+public_transport transportation modes. For other modes the max_changes parameter is ignored.
Enable transit leg change limit?
Maximum number of changes between transit legs in a journey. Must be at least 0.
object | optional
When enabled, range adds an arrival window to the arrival time, and results are returned for any journeys that arrive during this window.
In the results array, the properties of these multiple alternative results are sorted by travel_time in ascending order.
Disabled by default.
Used in public_transport, coach, bus, train, driving+train and cycling+public_transport transportation modes. For other modes the parameter is ignored.
boolean
Enable range search?
integer
Maximum number of results to return for each departure location.
Maximum value is 5.
integer
The width of the range window (in seconds).
The window is applied 'backwards' from the arrival time. For example, with an arrival_time of 9am and a range width of 1 hour, the results with the shortest journey time arriving between 8am and 9am will be returned.
If no results are found that fall within this arrival window, a single result will be returned which has the latest arrival time before the arrival window.
Maximum value is 43200 (12 hours).
Response Body
array[object]
The results array which is sorted lexicographically by the id attribute.
array[object]
Properties array. May contain multiple elements if range was specified, single element otherwise. Sorted by travel_time. Only the properties included in the request are returned
integer | optional
Travel time in seconds.
integer | optional
Distance in meters.
array[object] | optional
Distance breakdown, shows how much distance was covered by car, bus, etc.
car, parking, boarding, walk, bike, bike_parking, train, rail_national, rail_overground, rail_underground, rail_dlr, bus, cable_car, plane, ferry or coach
object | optional
array[object]
array[integer]
Id's of route parts that are covered by these tickets.
array[object]
Possible values: single, week, month or year.
ISO 4217 currency code.
object
date in extended ISO-8601 format
2023-02-06T14:00:00+03:00 or 2023-02-06T14:00:00Z.
date in extended ISO-8601 format
Example 2023-02-06T14:00:00+03:00 or 2023-02-06T14:00:00Z.
array[object]
integer
Travel time in seconds.
string | optional
Only available when type is public_transport.
string | optional
Only available when type is public_transport.
time hh:mm | optional
Local departure time. Only available when type is public_transport.
time hh:mm | optional
Local arrival time. Only available when type is public_transport.
array[string]
Array of unreachable locations
Examples
Request
Response Body
GET Request
A GET request is the simplest way to calculate a travel time matrix. A single calculation with limited parameters can be done by specifying the query parameters in the URL.
Query parameters
string
Mode of transport used.
Available options: walking, public_transport, driving, cycling.
date in extended ISO-8601 format | optional
If specified, this time will be used as the time of departure from the search location. One of departure_time or arrival_time must be specified.
date in extended ISO-8601 format | optional
If specified, this time will be used the time of arrival at the search location. One of arrival_time or departure_time must be specified.
float
Latitude of the search.
float
Longitude of the search.
string
The coordinates of the locations. Multiple locations should be listed in the format lat1_lng1,lat2_lng2,lat3_lng3,lat4_lng4 etc.
For example: 51.1234_0.1234,50.0000_-1.0000,52.0000_1.0000
Maximum number of locations is 2,000
string
Used for authenticating the request. Visit our developer portal to access your credentials or generate new ones.
string
Used for authenticating the request. Visit our developer portal to access your credentials or generate new ones.
Query response
Successful requests will return an HTTP 200 response.
Response schema - application/json
array[object]
The results array which is sorted lexicographically by the id attribute.
array[object]
The properties array containing the travel time.
integer | optional
Travel time in seconds.
array[string]
Array of unreachable locations. A location will be unreachable if either of the following is true:
- The required travel time is greater than 2 hours.
- The location is in an inaccessible location (e.g on a body of water, or in an extremely remote area).
- The location is more than 15 minutes walk from the nearest public transport stop/station (public transport mode only).
Example
Example request
https://api.traveltimeapp.com/v4/time-filter?type=public_transport&arrival_time=2023-02-06T15:00:00Z&search_lat=51.41070&search_lng=-0.15540&locations=51.45974_-0.16531,51.41494_-0.12492,51.41074_-0.21531,51.42942_-0.23343&app_id=YOUR_APP_ID&api_key=YOUR_APP_KEYPlease note that to send the GET request you will need to replace the YOUR_APP_ID and YOUR_APP_KEY values with your own credentials.