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

• locations

  array[object]
  Define your locations to use later in departure_searches or arrival_searches
  Show/Hide Child Attributes

  • id

    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.
  • coords

    object
    Show/Hide Child Attributes

    • lat

      float
      Latitude
    • lng

      float
      Longitude
• departure_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
  Show/Hide Child Attributes

  • id

    string
    Used to identify this specific search in the results array. MUST be unique among all searches.
  • departure_location_id

    string
    The id of the location we should start the search from. MUST reference an id from locations array
  • arrival_location_ids

    string
    The ids of locations we should arrive to. MUST reference ids from locations array. You can define a maximum of 2000 location ids
  • transportation

    object
    Transportation mode and related parameters. The default parameters are sensible and it is usually enough to only specify the type
    Show/Hide Child Attributes

    • 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)
    • disable_border_crossing

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

      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
    • walking_time

      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
    • driving_time_to_station

      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
    • cycling_time_to_station

      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
    • parking_time

      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.
    • boarding_time

      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
  • travel_time

    integer
    Travel time in seconds. Maximum value is 14400 (4 hours)
  • departure_time

    date in extended ISO-8601 format
    Leave departure location at no earlier than given time. Example - 2017-10-18T08:00:00Z
  • properties

    array[string]
    Properties to be returned about the points. Possible values: travel_time, distance, distance_breakdown, fares, route
  • range

    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
    Show/Hide Child Attributes

    • enabled

      boolean
      Enable range search?
    • max_results

      integer
      Maximum number of results to return. Limited to 5 results
    • width

      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
• arrival_searches

  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
  Show/Hide Child Attributes

  • id

    string
    Used to identify this specific search in the results array. MUST be unique among all searches.
  • departure_location_ids

    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
  • arrival_location_id

    string
    The id of the location we should arrive to. MUST reference an id from locations array
  • transportation

    object
    Transportation mode and related parameters. The default parameters are sensible and it is usually enough to only specify the type
    Show/Hide Child Attributes

    • 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)
    • disable_border_crossing

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

      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
    • walking_time

      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
    • driving_time_to_station

      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
    • cycling_time_to_station

      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
    • parking_time

      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.
    • boarding_time

      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
  • travel_time

    integer
    Travel time in seconds. Maximum value is 14400 (4 hours)
  • arrival_time

    date in extended ISO-8601 format
    Arrive at destination location at no later than given time. Example - 2017-10-18T08:00:00Z
  • properties

    array[string]
    Properties to be returned about the points. Possible values: travel_time, distance, distance_breakdown, fares, route
  • range

    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
    Show/Hide Child Attributes

    • enabled

      boolean
      Enable range search?
    • max_results

      integer
      Maximum number of results to return. Limited to 5 results
    • width

      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

• results

  array[object]
  The results array which is sorted lexicographically by the id attribute
  Show/Hide Child Attributes

  • search_id

    string
  • locations

    array[object]
    Show/Hide Child Attributes

    • id

      string
    • properties

      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
      Show/Hide Child Attributes

      • travel_time

        integer | optional
        Travel time in seconds
      • distance

        integer | optional
        Distance in meters
      • distance_breakdown

        array[object] | optional
        Distance breakdown, shows how much distance was covered by car, bus, etc.
        Show/Hide Child Attributes

        • mode

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

          integer
          Distance in meters
      • fares

        object | optional
        Show/Hide Child Attributes

        • breakdown

          array[object]
          Show/Hide Child Attributes

          • modes

            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 or coach
          • route_part_ids

            array[integer]
            Ids of route parts that are covered by these tickets
          • tickets

            array[object]
            Show/Hide Child Attributes

            • type

              string
              single, week, month or year
            • price

              float
            • currency

              string
              ISO 4217 currency code
        • tickets_total

          array[object]
          Show/Hide Child Attributes

          • type

            string
            single, week, month or year
          • price

            float
          • currency

            string
            ISO 4217 currency code
      • route

        object | optional
        Show/Hide Child Attributes

        • departure_time

          date yyyy-mm-ddThh:mm:ssZ
          Example 2016-06-21T11:00:00+03:00 or 2016-06-21T11:00:00Z
        • arrival_time

          date yyyy-mm-ddThh:mm:ssZ
          Example 2016-06-21T11:00:00+03:00 or 2016-06-21T11:00:00Z
        • parts

          array[object]
          Show/Hide Child Attributes

          • id

            integer
            A sequential id, used to relate route parts with fare data
          • type

            string
            basic, start_end, road or public_transport
          • mode

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

            string
          • distance

            integer
            Distance in meters
          • travel_time

            integer
            Travel time in seconds
          • coords

            array[object]
            Show/Hide Child Attributes

            • lat

              float
              Latitude
            • lng

              float
              Longitude
          • direction

            string | optional
            Only available when type is start_end
          • road

            string | optional
            May be present on parts where type is road
          • turn

            string | optional
            May be present on parts where type is road
          • line

            string | optional
            Only available when type is public_transport
          • departure_station

            string | optional
            Only available when type is public_transport
          • arrival_station

            string | optional
            Only available when type is public_transport
          • departs_at

            time hh:mm | optional
            Local departure time. Only available when type is public_transport
          • arrives_at

            time hh:mm | optional
            Local arrival time. Only available when type is public_transport
          • num_stops

            integer | optional
            Only available when type is public_transport
  • unreachable

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