Time Filter

Given origin and destination points filter out points that cannot be reached within specified time limit. Find out properties of connections between origin and destination points.

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.

Request Body Json Attributes

  • locations
    array[object]
    Define your locations to use later in departure_searches or arrival_searches
    • 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
      • 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
    • 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
      array[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
      • type
        string
        cycling, driving, driving+train, public_transport, walking, coach, bus, train, ferry, driving+ferry or cycling+ferry
      • 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 and driving+train transportation modes
      • walking_time
        integer | optional
        Maximum time (in seconds) of walking from source to a station/stop and from station/stop to destination. Default value is 900. Cannot be higher than travel_time. Used in public_transport, coach, bus, train and driving+train 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
      • parking_time
        integer | optional
        Time (in seconds) required to park a car. Default is 300. Cannot be higher than travel_time. Used in driving+train transportation mode
      • 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 and cycling+ferry transportation modes. For public_transport mode, pt_change_delay is used instead
    • travel_time
      integer
      Travel time in seconds
    • 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
      • 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
    • 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
      • type
        string
        cycling, driving, driving+train, public_transport, walking, coach, bus, train, ferry, driving+ferry or cycling+ferry
      • 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 and driving+train transportation modes
      • walking_time
        integer | optional
        Maximum time (in seconds) of walking from source to a station/stop and from station/stop to destination. Default value is 900. Cannot be higher than travel_time. Used in public_transport, coach, bus, train and driving+train 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
      • parking_time
        integer | optional
        Time (in seconds) required to park a car. Default is 300. Cannot be higher than travel_time. Used in driving+train transportation mode
      • 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 and cycling+ferry transportation modes. For public_transport mode, pt_change_delay is used instead
    • travel_time
      integer
      Travel time in seconds
    • 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
      • 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
    • search_id
      string
    • locations
      array[object]
      • 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
        • 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.
          • mode
            string
            car, parking, boarding, walk, bike, train, rail_national, rail_overground, rail_underground, rail_dlr, bus, cable_car, plane, ferry or coach
          • distance
            integer
            Distance in meters
        • fares
          object | optional
          • breakdown
            array[object]
            • modes
              array[string]
              Mode covered by the ticket, can be: car, parking, boarding, walk, bike, 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]
              • type
                string
                single, week, month or year
              • price
                float
              • currency
                string
                ISO 4217 currency code
          • tickets_total
            array[object]
            • type
              string
              single, week, month or year
            • price
              float
            • currency
              string
              ISO 4217 currency code
        • route
          object | optional
          • 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]
            • id
              int
              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, 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]
              • 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"
      ]
    }
  ]
}