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

  • array[object]
    Define your locations to use later in departure_searches or arrival_searches
    • array[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)
      • 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
        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, 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)
      • 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
        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, 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"
      ]
    }
  ]
}