departures: Departures from a given stop

In ptvapi: Access the 'Public Transport Victoria' Timetable API

Departures from a given stop

Description

departures retrieves all upcoming departures for a given stop ID and route type.

Usage

departures(
  stop_id,
  route_type,
  route_id = NULL,
  direction_id = NULL,
  platform_numbers = NULL,
  departs = Sys.time(),
  look_backwards = FALSE,
  max_results = 5,
  include_cancelled = FALSE,
  validate_results = TRUE,
  user_id = determine_user_id(),
  api_key = determine_api_key()
)

Arguments

stop_id	An integer stop ID returned by the stops_on_route or stops_nearby functions.
route_type	A route type which can be provided either as a non-negative integer code, or as a character: "Tram", "Train", "Bus", "Vline" or "Night Bus". Character inputs are not case-sensitive. Use the route_types function to extract a vector of all route types.
route_id	Optionally filter by a route ID. These can be obtained with the routes function.
direction_id	Optionally filter by a direction ID. These can be obtained with the directions_on_route function.
platform_numbers	Character vector. Optionally filter results by platform number. Despite the name, these are characters.
departs	POSIXct or Character. Optionally filter results to departures on or after the given value, according to either scheduled or estimated departure time. Characters are automatically converted to datetimes, and are assumed to be given as Melbourne time. Defaults to the current system time.
look_backwards	Boolean. Whether to look before departs. Use with caution (see Details). Defaults to FALSE.
max_results	Integer. The maximum number of departures to return for each route_id. Departures are ordered by estimated departure time, when available, and scheduled departure time otherwise. When set to 0, all departures after the given departs for the entire day are shown, and potentially some in the early hours of the next morning. Defaults to 5.
include_cancelled	Logical. Whether results should be returned if they have been cancelled. Metropolitan train services only. Defaults to FALSE.
validate_results	Boolean. If TRUE (the default), will apply additional filters to ensure that the arguments to departs, max_results, and route_id are respected if given.
user_id	Integer or character. A user ID or devid provided by Public Transport Victoria. Refer to ?ptvapi for more details.
api_key	Character. An API key, with dashes, provided by Public Transport Victoria. Refer to ?ptvapi for more details.

Details

Filtering departures: The API supports filtering by departure time, to show the departures after the given time. However, its behaviour is unpredictable, returning departures around the given time, both before and after. We apply an additional filter once the results are retrieved to ensure that only departures at or after the given departs datetime are shown.

It's not clear what functionality look_backwards has. It's included here regardless. Moreover, it's not clear how the API treats route_id or max_results. We filter the results after retrieval, to ensure that departs, max_results, and route_id are respected. This additional validation can be disabled by setting validate_results = TRUE.

Value

A tibble consisting of the following columns:

• stop_id

• route_id

• run_id (deprecated, use run_ref instead)

• run_ref

• direction_id

• disruption_ids

• scheduled_departure

• estimated_departure

• at_platform

• platform_number

• flags

• departure_sequence

Examples

## Not run: 
departures(stop_id = 1071, route_type = "Train")
departures(stop_id = 1071, route_type = 0)

departures(
  stop_id = 1071,
  route_type = "Train",
  platform_numbers = c(4, 5)
)

departures(
  stop_id = 1071,
  route_type = "Train",
  route_id = 6
)

departures(
  stop_id = 1071,
  route_type = "Train",
  departs = "2020-06-23 17:05:00"
)


## End(Not run)

ptvapi documentation built on May 29, 2024, 4:48 a.m.