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.

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, B }
  • 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 or arrival_searches
    • string
      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.
    • object
      • float
        Latitude
      • float
        Longitude
  • 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
    • string
      Used to identify this specific search in the results array. MUST be unique among all searches.
    • The id of the location we should start the search from. MUST reference an id from locations array
    • The ids of locations we should arrive to. MUST reference ids from locations array. You can define a maximum of 2000 location ids
    • Transportation 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 or cycling+public_transport (only in Netherlands)
      • boolean | optional
        If set to true, disables crossing of country borders. This feature is only available with driving transportation mode and is enabled by default (false).
      • 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
        Refers 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 limits are independent and not cumulative - in the worst case the a traveler can walk for twice the stated limit in one journey (time to station + time from station).
        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
        Maximum time (in seconds) of driving from source to train station. Default value is 1800. Cannot be higher than travel_time. Used in driving+train transportation mode
      • integer | optional
        Maximum time (in seconds) of cycling (including any ferry transfers) from source to a station or stop. Default value is 900. Cannot be higher than travel_time. Used in cycling+public_transport transportation mode
      • integer | optional
        Time (in seconds) required to park a car or a bike. Default 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 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
    • integer
      Travel time in seconds. Maximum value is 14400 (4 hours)
    • date in extended ISO-8601 format
      Leave 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 | optional
      Range 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 with public_transport, coach, bus, train and driving+train transportation modes. For other modes range search parameters are ignored
      • boolean
        Enable range search?
      • integer
        Maximum number of results to return. Limited to 5 results
      • integer
        Search range width in seconds. width along with departure_time specify departure interval. For example, if you set departure_time to 9am and width 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 to 12 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
    • string
      Used 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 of 2000 location ids
    • The id of the location we should arrive to. MUST reference an id from locations array
    • Transportation 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 or cycling+public_transport (only in Netherlands)
      • boolean | optional
        If set to true, disables crossing of country borders. This feature is only available with driving transportation mode and is enabled by default (false).
      • 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
        Refers 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 limits are independent and not cumulative - in the worst case the a traveler can walk for twice the stated limit in one journey (time to station + time from station).
        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
        Maximum time (in seconds) of driving from source to train station. Default value is 1800. Cannot be higher than travel_time. Used in driving+train transportation mode
      • integer | optional
        Maximum time (in seconds) of cycling (including any ferry transfers) from source to a station or stop. Default value is 900. Cannot be higher than travel_time. Used in cycling+public_transport transportation mode
      • integer | optional
        Time (in seconds) required to park a car or a bike. Default 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 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
    • integer
      Travel time in seconds. Maximum value is 14400 (4 hours)
    • date in extended ISO-8601 format
      Arrive 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 | optional
      Range 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 with public_transport, coach, bus, train and driving+train transportation modes. For other modes range search parameters are ignored
      • boolean
        Enable range search?
      • integer
        Maximum number of results to return. Limited to 5 results
      • integer
        Search range width in seconds. width along with arrival_time specify arrival interval. For example, if you set arrival_time to 9am and width 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 to 12 hours

Response Body Json Attributes

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