TravelTime Docs logo
TravelTime API
ArcGIS plugin
QGIS plugin
Alteryx plugin

Travel Time Matrix (Time Filter)anchor icon

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 travel time matrixanchor icon

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 thearrival_location_idinto departure_location_id and departure_location_ids into arrival_location_ids).

Use Casesanchor icon

Office Relocationanchor icon

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 usetime-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 Bodyanchor icon

array[object]

Define your locations to use later in departure_searches or arrival_searches.

Hide child attributes

You will have to reference this id in your searches. It will also be used in the response body. Must be unique among all locations.

The coordinates of the locations.

Show child attributes

Latitude.

Longitude.

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.

Hide child attributes

Used to identify each search in the results array. Must be unique among all searches.

The id of the location to depart from. Must reference an id from the locations array.

The ids of the locations to arrive at. Must reference ids from the locations array.
You can define a maximum of 2000 location ids.

Transportation mode and related parameters. type is a mandatory field, but all other fields are optional and default values are used if not specified.

Show child attributes

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).

If set to true, the crossing of country borders is disabled. Only available with the driving transportation mode, and is enabled by default (false).

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.

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.

Show child attributes

Enable transit leg change limit?

Maximum number of changes between transit legs in a journey. Must be at least 0.

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.

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.

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.

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.

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.

Maximum journey time (in seconds).
Maximum value is 14400 (4 hours) as standard. To discuss increasing this, please contact sales@traveltime.com.

date in extended ISO-8601 format

Leave departure location at no earlier than given time. In ISO 8601 format. For example:
2022-07-01T06:00:00Z (representing UTC)
2022-07-01T06:00:00-05:00 (representing New York on Standard Time: UTC-05:00)

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)

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.

Show child attributes

Enable range search?

Maximum number of results to return for each arrival location.
Maximum value is 5.

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.

Hide child attributes

Used to identify each search in the results array. Must be unique among all searches.

The ids of the locations to depart from. Must reference ids from the locations array.
You can define a maximum of 2000 location ids.

The id of the location to arrive at. Must reference an id from the locations array.

Transportation mode and related parameters. type is a mandatory field, but all other fields are optional and default values are used if not specified.

Show child attributes

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).

If set to true, the crossing of country borders is disabled. Only available with the driving transportation mode, and is enabled by default (false).

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.

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.

Show child attributes

Enable transit leg change limit?

Maximum number of changes between transit legs in a journey. Must be at least 0.

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.

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.

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.

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.

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.

Maximum journey time (in seconds).
Maximum value is 14400 (4 hours) as standard. To discuss increasing this, please contact sales@traveltime.com.

date in extended ISO-8601 format

Be at arrival location at no later than given time. In ISO 8601 format. For example:
2022-07-01T06:00:00Z (representing UTC)
2022-07-01T06:00:00-05:00 (representing New York on Standard Time: UTC-05:00)

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)

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.

Show child attributes

Enable range search?

Maximum number of results to return for each departure location.
Maximum value is 5.

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 Bodyanchor icon

array[object]

The results array which is sorted lexicographically by the id attribute.

Hide child attributes

array[object]

Hide child attributes

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

Hide child attributes

Travel time in seconds.

Distance in meters.

Distance breakdown, shows how much distance was covered by car, bus, etc.

Show child attributes

car, parking, boarding, walk, bike, bike_parking, train, rail_national, rail_overground, rail_underground, rail_dlr, bus, cable_car, plane, ferry or coach

Show child attributes
Show child attributes

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 or coach.

Id's of route parts that are covered by these tickets.

Show child attributes
Show child attributes

Possible values: single, week, month or year.

Show child attributes

date in extended ISO-8601 format

2022-07-01T06:00:00+03:00 or 2022-07-01T06:00:00Z.

date in extended ISO-8601 format

Example 2022-07-01T06:00:00+03:00 or 2022-07-01T06:00:00Z.

Show child attributes

A sequential id, used to relate route parts with fare data.

Possible values: basic, start_end, road or public_transport.

car, parking, boarding, walk, bike, bike_parking, train, rail_national, rail_overground, rail_underground, rail_dlr, bus, cable_car, plane, ferry or coach.

Distance in meters.

Travel time in seconds.

Only available when type is start_end.

May be present on parts where type is road.

May be present on parts where type is road.

Only available when type is public_transport.

Only available when type is public_transport.

Only available when type is public_transport.

Local departure time. Only available when type is public_transport.

Local arrival time. Only available when type is public_transport.

Only available when type is public_transport.

array[string]

Array of unreachable locations

Examplesanchor icon

Requestanchor icon

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",
    "max_changes": {
          "enabled": true,
          "limit": 3
        }
      },
      "departure_time": "2022-05-27T08:00:00Z",
      "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": "2022-05-27T08:00:00Z",
      "travel_time": 1900,
      "properties": [
        "travel_time",
        "distance",
        "distance_breakdown",
        "fares"
      ]
    }
  ]
}

Response Bodyanchor icon

{
  "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"
      ]
    }
  ]
}

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",
    "max_changes": {
          "enabled": true,
          "limit": 3
        }
      },
      "departure_time": "2022-05-27T08:00:00Z",
      "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": "2022-05-27T08:00:00Z",
      "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"
      ]
    }
  ]
}