Distance Matrix (Time Filter)
Given origin and destination points filter out points that cannot be reached within specified time limit. Find out travel times, distances and costs between an origin and up to 2,000 destination points.
Learn more about our distance matrix service
Making a distance matrix
To create a matrix of distances between many locations you will need to use multiple arrival and destination 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 }
For modes other than walking and cycling this needs to be repeated for departure searches (swapping the arrival_location_id
into departure_location_id
and departure_location_ids
into arrival_location_ids
).
Use Cases
Office Relocation
Your company wants to relocate. You have coordinates of potential new office locations and coordinates of your employees’ homes. You want your employees to be at work at 9am, you can use time-filter
to find the office that most of your employees will be able to reach within a certain period of time using public transport.
Access URL: https://api.traveltimeapp.com/v4/time-filter
Request Body Json Attributes
-
array[object]Define your locations to use later in
departure_searches
orarrival_searches
-
array[object]Searches based on departure time. Leave departure location at no earlier than given time. This allows you to specify a single departure location and multiple arrival locations. You can define a maximum of
10
searches-
stringUsed to identify this specific search in the results array. MUST be unique among all searches.
-
stringThe id of the location we should start the search from. MUST reference an id from
locations
array -
stringThe ids of locations we should arrive to. MUST reference ids from
locations
array. You can define a maximum of2000
location ids -
objectTransportation mode and related parameters. The default parameters are sensible and it is usually enough to only specify the
type
-
string
cycling
,driving
,driving+train
(only in Great Britain),public_transport
,walking
,coach
,bus
,train
,ferry
,driving+ferry
,cycling+ferry
orcycling+public_transport
(only in Netherlands) -
boolean | optionalIf set to
true
, disables crossing of country borders. This feature is only available withdriving
transportation mode and is enabled by default (false
). -
integer | optionalTime (in seconds) needed to board public transportation vehicle. Default is
0
. Cannot be higher thantravel_time
. Used inpublic_transport
,coach
,bus
,train
,driving+train
andcycling+public_transport
transportation modes -
integer | optionalRefers to the maximum time limit of walking when geting on and off public transport i.e:
- maximum time (in seconds) of walking from the source to a stop (or station) and
- maximum time (in seconds) of walking from a stop (or station) to the destination.
The default value is900
. Cannot be higher thantravel_time
.
Used inpublic_transport
,coach
,bus
,train
,driving+train
andcycling+public_transport
transportation modes -
integer | optionalMaximum time (in seconds) of driving from source to train station. Default value is
1800
. Cannot be higher thantravel_time
. Used indriving+train
transportation mode -
integer | optionalMaximum time (in seconds) of cycling (including any ferry transfers) from source to a station or stop. Default value is
900
. Cannot be higher thantravel_time
. Used incycling+public_transport
transportation mode -
integer | optionalTime (in seconds) required to park a car or a bike. Default is
300
. Cannot be higher thantravel_time
. Used indriving+train
andcycling+public_transport
transportation modes. -
integer | optionalTime (in seconds) required to board a ferry. Default is
0
. Cannot be higher thantravel_time
. Used inpublic_transport
,ferry
,driving+ferry
,cycling+ferry
andcycling+public_transport
transportation modes. Forpublic_transport
mode,pt_change_delay
is used instead
-
-
integerTravel time in seconds. Maximum value is
14400
(4 hours) -
date in extended ISO-8601 formatLeave departure location at no earlier than given time. Example -
2017-10-18T08:00:00Z
-
array[string]Properties to be returned about the points. Possible values:
travel_time
,distance
,distance_breakdown
,fares
,route
-
object | optionalRange search parameters. By default range search is disabled. When range search is enabled multiple alternative result properties are returned and properties are sorted by
travel_time
in ascending order.
Note: range search only works withpublic_transport
,coach
,bus
,train
anddriving+train
transportation modes. For other modes range search parameters are ignored-
booleanEnable range search?
-
integerMaximum number of results to return. Limited to
5
results -
integerSearch range width in seconds.
width
along withdeparture_time
specify departure interval. For example, if you setdeparture_time
to 9am andwidth
to 1 hour, we will return results with lowest travel time that have departure time between 9am and 10am.
If no results are found that fall within this interval, we will return single result that has the earliest departure time.
Range width is limited to12
hours
-
-
-
array[object]Searches based on arrival time. Arrive at destination location at no later than given time. This allows you to specify a single arrival location and multiple departure locations. You can define a maximum of
10
searches-
stringUsed to identify this specific search in the results array. MUST be unique among all searches.
-
array[string]The ids of locations we should start the search from. MUST reference ids from
locations
array. You can define a maximum of2000
location ids -
stringThe id of the location we should arrive to. MUST reference an id from
locations
array -
objectTransportation mode and related parameters. The default parameters are sensible and it is usually enough to only specify the
type
-
string
cycling
,driving
,driving+train
(only in Great Britain),public_transport
,walking
,coach
,bus
,train
,ferry
,driving+ferry
,cycling+ferry
orcycling+public_transport
(only in Netherlands) -
boolean | optionalIf set to
true
, disables crossing of country borders. This feature is only available withdriving
transportation mode and is enabled by default (false
). -
integer | optionalTime (in seconds) needed to board public transportation vehicle. Default is
0
. Cannot be higher thantravel_time
. Used inpublic_transport
,coach
,bus
,train
,driving+train
andcycling+public_transport
transportation modes -
integer | optionalRefers to the maximum time limit of walking when geting on and off public transport i.e:
- maximum time (in seconds) of walking from the source to a stop (or station) and
- maximum time (in seconds) of walking from a stop (or station) to the destination.
The default value is900
. Cannot be higher thantravel_time
.
Used inpublic_transport
,coach
,bus
,train
,driving+train
andcycling+public_transport
transportation modes -
integer | optionalMaximum time (in seconds) of driving from source to train station. Default value is
1800
. Cannot be higher thantravel_time
. Used indriving+train
transportation mode -
integer | optionalMaximum time (in seconds) of cycling (including any ferry transfers) from source to a station or stop. Default value is
900
. Cannot be higher thantravel_time
. Used incycling+public_transport
transportation mode -
integer | optionalTime (in seconds) required to park a car or a bike. Default is
300
. Cannot be higher thantravel_time
. Used indriving+train
andcycling+public_transport
transportation modes. -
integer | optionalTime (in seconds) required to board a ferry. Default is
0
. Cannot be higher thantravel_time
. Used inpublic_transport
,ferry
,driving+ferry
,cycling+ferry
andcycling+public_transport
transportation modes. Forpublic_transport
mode,pt_change_delay
is used instead
-
-
integerTravel time in seconds. Maximum value is
14400
(4 hours) -
date in extended ISO-8601 formatArrive at destination location at no later than given time. Example -
2017-10-18T08:00:00Z
-
array[string]Properties to be returned about the points. Possible values:
travel_time
,distance
,distance_breakdown
,fares
,route
-
object | optionalRange search parameters. By default range search is disabled. When range search is enabled multiple alternative result properties are returned and properties are sorted by
travel_time
in ascending order.
Note: range search only works withpublic_transport
,coach
,bus
,train
anddriving+train
transportation modes. For other modes range search parameters are ignored-
booleanEnable range search?
-
integerMaximum number of results to return. Limited to
5
results -
integerSearch range width in seconds.
width
along witharrival_time
specify arrival interval. For example, if you setarrival_time
to 9am andwidth
to 1 hour, we will return results with lowest travel time that have arrival time between 8am and 9am.
If no results are found that fall within this interval, we will return single result that has the latest arrival time.
Range width is limited to12
hours
-
-
Response Body Json Attributes
-
array[object]The results array which is sorted lexicographically by the
id
attribute-
string
-
array[object]
-
string
-
array[object]Properties array. May contain multiple elements if
range
was specified, single element otherwise. Sorted bytravel_time
. Only the properties included in the request are returned-
integer | optionalTravel time in seconds
-
integer | optionalDistance in meters
-
array[object] | optionalDistance breakdown, shows how much distance was covered by
car
,bus
, etc. -
object | optional
-
array[object]
-
array[string]Mode covered by the ticket, can be:
car
,parking
,boarding
,walk
,bike
,bike_parking
,train
,rail_national
,rail_overground
,rail_underground
,rail_dlr
,bus
,cable_car
,plane
,ferry
orcoach
-
array[integer]Ids of route parts that are covered by these tickets
-
array[object]
-
-
array[object]
-
-
object | optional
-
date yyyy-mm-ddThh:mm:ssZExample
2016-06-21T11:00:00+03:00
or2016-06-21T11:00:00Z
-
date yyyy-mm-ddThh:mm:ssZExample
2016-06-21T11:00:00+03:00
or2016-06-21T11:00:00Z
-
array[object]
-
integerA sequential id, used to relate route parts with fare data
-
string
basic
,start_end
,road
orpublic_transport
-
string
car
,parking
,boarding
,walk
,bike
,bike_parking
,train
,rail_national
,rail_overground
,rail_underground
,rail_dlr
,bus
,cable_car
,plane
,ferry
orcoach
-
string
-
integerDistance in meters
-
integerTravel time in seconds
-
array[object]
-
string | optionalOnly available when
type
isstart_end
-
string | optionalMay be present on parts where
type
isroad
-
string | optionalMay be present on parts where
type
isroad
-
string | optionalOnly available when
type
ispublic_transport
-
string | optionalOnly available when
type
ispublic_transport
-
string | optionalOnly available when
type
ispublic_transport
-
time hh:mm | optionalLocal departure time. Only available when
type
ispublic_transport
-
time hh:mm | optionalLocal arrival time. Only available when
type
ispublic_transport
-
integer | optionalOnly available when
type
ispublic_transport
-
-
-
-
-
array[string]Ids of locations that cannot be reached within the specified
travel_time
-
Example Request
POST /v4/time-filter HTTP/1.1
Host: api.traveltimeapp.com
Content-Type: application/json
Accept: application/json
X-Application-Id: ...
X-Api-Key: ...
{
"locations": [
{
"id": "London center",
"coords": {
"lat": 51.508930,
"lng": -0.131387
}
},
{
"id": "Hyde Park",
"coords": {
"lat": 51.508824,
"lng": -0.167093
}
},
{
"id": "ZSL London Zoo",
"coords": {
"lat": 51.536067,
"lng": -0.153596
}
}
],
"departure_searches": [
{
"id": "forward search example",
"departure_location_id": "London center",
"arrival_location_ids": [
"Hyde Park",
"ZSL London Zoo"
],
"transportation": {
"type": "bus"
},
"departure_time": "",
"travel_time": 1800,
"properties": [
"travel_time"
],
"range": {
"enabled": true,
"max_results": 3,
"width": 600
}
}
],
"arrival_searches": [
{
"id": "backward search example",
"departure_location_ids": [
"Hyde Park",
"ZSL London Zoo"
],
"arrival_location_id": "London center",
"transportation": {
"type": "public_transport"
},
"arrival_time": "",
"travel_time": 1900,
"properties": [
"travel_time",
"distance",
"distance_breakdown",
"fares"
]
}
]
}
Response Body
{
"results": [
{
"search_id": "backward search example",
"locations": [
{
"id": "Hyde Park",
"properties": [
{
"travel_time": 1696,
"distance": 0,
"distance_breakdown": [
{
"mode": "walk",
"distance": 839
},
{
"mode": "bus",
"distance": 2415
}
],
"fares": {
"breakdown": [
{
"modes": [
"bus"
],
"route_part_ids": [
2
],
"tickets": [
{
"type": "single",
"price": 1.5,
"currency": "GBP"
},
{
"type": "week",
"price": 21,
"currency": "GBP"
},
{
"type": "month",
"price": 80.7,
"currency": "GBP"
},
{
"type": "year",
"price": 840,
"currency": "GBP"
}
]
}
],
"tickets_total": [
{
"type": "single",
"price": 1.5,
"currency": "GBP"
},
{
"type": "week",
"price": 21,
"currency": "GBP"
},
{
"type": "month",
"price": 80.7,
"currency": "GBP"
},
{
"type": "year",
"price": 840,
"currency": "GBP"
}
]
}
}
]
}
],
"unreachable": [
"ZSL London Zoo"
]
},
{
"search_id": "forward search example",
"locations": [
{
"id": "Hyde Park",
"properties": [
{
"travel_time": 1753
},
{
"travel_time": 1804
},
{
"travel_time": 1815
}
]
}
],
"unreachable": [
"ZSL London Zoo"
]
}
]
}