ptvapi: A package for accessing the Public Transport Victoria Timetable API

Description

Accessing the Public Transport Victoria Timetable API reqiures a user ID (also called a devid) and an API key. These can be accessed by contacting Public Transport Victoria. See https://www.ptv.vic.gov.au/footer/data-and-reporting/datasets/ptv-timetable-api/

The user ID and API key can be entered directly into all functions. Alternatively, all functions will pick up on the PTV_USER_ID and API_KEY environment variables, if defined.

All API requests use SSL by default. To disable this, and to use the http API endpoints rather than the https API endpoints, set the option:

options(use_insecure_ptv_connection = TRUE)

Details

This is an unofficial wrapper of the Public Transport Victoria Timetable API. The author(s) of this package are unaffiliated with Public Transport Victoria.

Author(s)

Maintainer: David Neuzerling david@neuzerling.com [copyright holder]

See Also

Useful links:

• https://github.com/mdneuzerling/ptvapi

• Report bugs at https://github.com/mdneuzerling/ptvapi/issues

Examples

## Not run: 
# tibble of all routes
routes()

# Search for routes by name (case insensitive, partial matching supported)
routes(route_name = "Frankston")

# All current disruptions
disruptions(disruption_status = "current")

# Train stops near Flinders Street Station
stops_nearby(
  latitude = -37.8183,
  longitude = 144.9671,
  route_types = "Train"
)

# Upcoming train departures from Flinders Street Station
departures(stop_id = 1071, route_type = "Train")

## End(Not run)

Submit a GET request to the PTV API

Description

Submit a GET request to the PTV API

Usage

PTVGET(
  request,
  user_id = determine_user_id(),
  api_key = determine_api_key(),
  ...
)

Arguments

Value

A HTTP response. Content can be accessed with httr::content.

Obtaining API authentication details

You will need to obtain a user ID (also called a devid) and an API key from Public Transport Victoria. These are obtained by email. Instructions are available at https://www.ptv.vic.gov.au/footer/data-and-reporting/datasets/ptv-timetable-api/. You may pass these two pieces of information directly to the function, or you can set the PTV_USER_ID and PTV_API_KEY environment variables.

Suffix a parameter to a HTML request

Description

Parameters are suffixed to a URL, like so: "request?para1=value1&para2=value2". The first parameter is suffixed with "?" and all others after that "&". This function will determine the correct suffix based on the presence of "&" in the request.

Usage

add_parameter(
  request,
  parameter_name,
  parameter_value,
  .combine = "repeat_name"
)

Arguments

Details

There is no standardised way to combine multiple values for a parameter. You should see how your API expects multiple values to be provided to the same parameter. This function allows for the following strategies. If any other value is provided, then the values will be concatenated and separated with the provided value.

• "repeat_name" (default). The values of the parameter are repeated with the parameter name. For example, ⁠("request", "para", c(1, 2))⁠ will return "request?para=1&para=2".

• "with_commas". The values of the parameter are concatenated and separated with commas. For example, ⁠("request", "para", c(1, 2))⁠ will return "request?para=1,2".

• "with_commas". The values of the parameter are concatenated and separated with the ASCII keycode in hexadecimal for a comma ("%2C"). For example, ⁠("request", "para", c(1, 2))⁠ will return "request?para=1%2C2".

Value

Character. The request with suffixed parameters.

Examples

## Not run: 
ptvapi:::add_parameter("www.example.com", "animal", "crocodile")
ptvapi:::add_parameter(
  "www.example.com",
  "numbers",
  c(1, 2, 3),
  .combine = "repeat_names"
)
## End(Not run)

Suffix one or many parameters to a HTML request

Description

Parameters are suffixed to a URL, like so: "request?para1=value1&para2=value2". The first parameter is suffixed with "?" and all others after that "&". This function will determine the correct suffix based on the presence of "&" in the request.

Usage

add_parameters(request, ..., .combine = "repeat_name")

Arguments

Details

There is no standardised way to combine multiple values for a parameter. You should see how your API expects multiple values to be provided to the same parameter. This function allows for the following strategies. If any other value is provided, then the values will be concatenated and separated with the provided value.

• "repeat_name" (default). The values of the parameter are repeated with the parameter name. For example, ⁠("request", "para", c(1, 2))⁠ will return "request?para=1&para=2".

• "with_commas". The values of the parameter are concatenated and separated with commas. For example, ⁠("request", "para", c(1, 2))⁠ will return "request?para=1,2".

• "with_commas". The values of the parameter are concatenated and separated with the ASCII keycode in hexadecimal for a comma ("%2C"). For example, ⁠("request", "para", c(1, 2))⁠ will return "request?para=1%2C2".

Value

Character. The request with suffixed parameters.

Examples

## Not run: 
ptvapi:::add_parameters("www.example.com", animal = crocodile)
ptvapi:::add_parameters(
  "www.example.com",
  animal = crocodile,
  food = "cherries"
)
ptvapi:::add_parameters(
  "www.example.com",
  animal = crocodile,
  numbers = c(1, 2, 3),
  .combine = "repeat_names"
)
## End(Not run)

Convert the contents of a disruptions API call to a single tibble

Description

Disruptions API responses contain an element for every service type, eg. metro train, taxis, Skybus. Normally we would map-reduce the content of an API call with a function analogous to disruption_to_tibble. But because of the extra layer of nesting in the response, we have to map-reduce the service types first.

Usage

all_disruptions_to_tibble(disruptions_content)

Arguments

Details

Note that we return an empty tibble if there are no disruptions, so that this situation is omitted.

Value

A tibble with the following columns:

• disruption_mode

• disruption_mode_description

• disruption_id

• title

• url

• description

• disruption_status

• disruption_type

• published_on

• last_updated

• from_date

• to_date

• routes

• stops

• colour

• display_on_board

• display_status

Assert that the API has returned the expected attributes

Description

The attributes returned by the API calls should be follow the API schema. This function compares received attributes against a vector of expected attributes, and returns an error if the two do not match. Unfortunately, there is no easy fix for this error: the package developer(s) must be notified, so that they can align the functions against the API schema.

Usage

assert_correct_attributes(received_attributes, expected_attributes)

Arguments

Value

An error if the column names are not as expected.

Retrieve route types, using cached values if possible

Description

Route types will change extraordinarily rarely — this would require PTV to add a new route type akin to "train" or "bus". To avoid querying the API too much, we prefer to use cached values for route type translation wherever possible. This function effectively wraps route_types, returning cached results if possible or caching results otherwise. Note that if a user specifically calls route_types then we do not return cached results.

We use the pkg_env as a cache, which is an environment created on package load. This is not truly private — users could still access this as an internal value. But it's effectively "out of the way".

Usage

cached_route_types(
  user_id = determine_user_id(),
  api_key = determine_api_key()
)

Arguments

Value

A named integer vector in which the values are the route type descriptions, and the names of the vector are the route type numbers.

Convert a datetime returned by the PTV API into Melbourne time

Description

Convert a datetime returned by the PTV API into Melbourne time

Usage

convert_to_melbourne_time(datetime)

Arguments

Value

A datetime in the Melbourne timezone.

Convert a single departure to a tibble

Description

This function is designed to parse the content returned by the interior steps of the departures functions.

Usage

departure_to_tibble(departure)

Arguments

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

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

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)

Convert a numeric route type to a human-friendly description

Description

This function effectively wraps the results of route_types to translate a route type to a human-readable form, such as translating 0 to "Train". This function is not vectorised.

Usage

describe_route_type(
  route_type,
  user_id = determine_user_id(),
  api_key = determine_api_key()
)

Arguments

Value

character

Directions for a given direction ID

Description

This function returns all directions with a given ID. Directions that share an ID are not necessarily related, especially if not filtering by route type. It's advised to use to the directions_on_route function to search for directions of interest.

Usage

directions(
  direction_id,
  route_type = NULL,
  user_id = determine_user_id(),
  api_key = determine_api_key()
)

Arguments

Value

A tibble consisting of the following columns:

• direction_id

• direction_name,

• route_id

• route_type

• route_type_description

• route_direction_description

Examples

## Not run: 
directions(direction_id = 5)
directions(direction_id = 5, route_type = "Train")
directions(direction_id = 5, route_type = 0)

## End(Not run)

Directions on a given route

Description

Directions on a given route

Usage

directions_on_route(
  route_id,
  user_id = determine_user_id(),
  api_key = determine_api_key()
)

Arguments

Value

A tibble consisting of the following columns:

• direction_id

• direction_name,

• route_id

• route_type

• route_type_description

• route_direction_description

Examples

## Not run: 
directions_on_route(6)

## End(Not run)

Information on a particular disruption

Description

This function can be used when the integer disruption ID is already known. This can be searched for with either disruptions, disruptions_on_route, or disruptions_at_stop functions.

Usage

disruption_information(
  disruption_id,
  user_id = determine_user_id(),
  api_key = determine_api_key()
)

Arguments

Value

A tibble with the following columns:

• disruption_mode

• disruption_mode_description

• disruption_id

• title

• url

• description

• disruption_status

• disruption_type

• published_on

• last_updated

• from_date

• to_date

• routes

• stops

• colour

• display_on_board

• display_status

Examples

## Not run: 
disruption_information(206639)

## End(Not run)

Retrieve a translation from description mode number to description mode name

Description

Disruption mode types (eg. "metro_train", "metro_tram", "school_bus", "taxi") have corresponding integer IDs. This function retrieves a named vector in which the values are the disruption mode descriptions, and the names of the vector are the description mode numbers. Note that disruption mode names are in snake case, that is, all lower case with underscores between words.

Usage

disruption_modes(user_id = determine_user_id(), api_key = determine_api_key())

Arguments

Value

A named vector in which the values are the disruption mode descriptions, and the names of the vector are the description mode numbers.

Examples

## Not run: disruption_modes()

Convert a single disruption to a tibble

Description

This function is designed to parse the content returned by the interior steps of the disruptions_on_route and disruptions_at_stop functions.

Usage

disruption_to_tibble(disruption)

Arguments

Value

A tibble with the following columns:

• disruption_id

• title

• url

• description

• disruption_status

• disruption_type

• published_on

• last_updated

• from_date

• to_date

• routes

• stops

• colour

• display_on_board

• display_status

Information for all disruptions

Description

Information for all disruptions

Usage

disruptions(
  route_types = NULL,
  disruption_modes = NULL,
  disruption_status = NULL,
  user_id = determine_user_id(),
  api_key = determine_api_key()
)

Arguments

Value

A tibble with the following columns:

• disruption_mode

• disruption_mode_description

• disruption_id

• title

• url

• description

• disruption_status

• disruption_type

• published_on

• last_updated

• from_date

• to_date

• routes

• stops

• colour

• display_on_board

• display_status

Examples

## Not run: 
disruptions()
disruptions(route_types = c("Train", "Tram"))
disruptions(disruption_modes = c(0, 1))
disruptions(disruption_status = "current")

## End(Not run)

Disruptions at a given stop

Description

Disruptions at a given stop

Usage

disruptions_at_stop(
  stop_id,
  disruption_status = NULL,
  user_id = determine_user_id(),
  api_key = determine_api_key()
)

Arguments

Value

A tibble with the following columns:

• disruption_mode

• disruption_mode_description

• disruption_id

• title

• url

• description

• disruption_status

• disruption_type

• published_on

• last_updated

• from_date

• to_date

• routes

• stops

• colour

• display_on_board

• display_status

Examples

## Not run: 
disruptions_at_stop(1071)
disruptions_at_stop(1071, disruption_status = "current")

## End(Not run)

Disruptions on a given route

Description

Disruptions on a given route

Usage

disruptions_on_route(
  route_id,
  stop_id = NULL,
  disruption_status = NULL,
  user_id = determine_user_id(),
  api_key = determine_api_key()
)

Arguments

Value

A tibble with the following columns:

• disruption_mode

• disruption_mode_description

• disruption_id

• title

• url

• description

• disruption_status

• disruption_type

• published_on

• last_updated

• from_date

• to_date

• routes

• stops

• colour

• display_on_board

• display_status

Examples

## Not run: 
disruptions_on_route(6)
disruptions_on_route(6, stop_id = 1071)
disruptions_on_route(6, disruption_status = "current")

## End(Not run)

Calculate a fare estimate between zones

Description

Retrieve fare information for a journey through the given zones. Also supports journey touch on and off times, to accommodate for discounts.

Usage

fare_estimate(
  min_zone,
  max_zone,
  journey_touch_on = NULL,
  journey_touch_off = NULL,
  journey_in_free_tram_zone = FALSE,
  travelled_route_types = NULL,
  user_id = determine_user_id(),
  api_key = determine_api_key()
)

Arguments

Value

A data frame consisting of one row for each passenger_type, and the following columns:

• min_zone

• max_zone

• unique_zones

• early_bird

• free_tram_zone

• weekend_journey

• passenger_type

• fare_2_hour_peak

• fare_2_hour_off_peak

• fare_daily_peak

• fare_daily_off_peak

• pass_7_days

• pass_28_to_69_day_per_day

• pass_70_plus_day_per_day

• weekend_cap

• holiday_cap

Examples

## Not run: 
fare_estimate(min_zone = 1, max_zone = 2)

fare_estimate(min_zone = 1, max_zone = 1, journey_in_free_tram_zone = TRUE)

fare_estimate(
  min_zone = 1,
  max_zone = 2,
  travelled_route_types = c("Train", "Tram")
)

fare_estimate(
  min_zone = 1,
  max_zone = 2,
  journey_touch_on = "2020-06-21 07:31:00",
  journey_touch_off = "2020-06-21 08:45:00"
 )

## End(Not run)

Filter parsed departures content according to user input

Description

The departures API call isn't always reliable. This function will take a tibble of parsed departures content and filter it according to the following inputs, if they are not NULL:

• Only departures after the given departs

• Only departures on the given route ID

• The next max_results departures per route ID, if max_results is not 0.

Usage

filter_departures(parsed, departs = NULL, route_id = NULL, max_results = NULL)

Arguments

Value

A filtered tibble.

Generate a URL with devid and signature

Description

Generate a URL with devid and signature

Usage

generate_request_url(
  request,
  user_id = determine_user_id(),
  api_key = determine_api_key()
)

Arguments

Value

A complete URL character that can be queried with httr

Convert a single geopath to a tibble

Description

This function is designed to parse the geopath content returned by the interior steps of some functions. If geopath data is requested, that content will contain a list of geopaths for each route. This function is designed to parse one of those geopaths into a tibble.

Usage

geopath_to_tibble(geopath)

Arguments

Value

A tibble of routes, with the following columns:

• direction_id

• valid_from

• valid_to

• paths

Convert an input to a form that can be used in a URL.

Description

Before a character can be used as part of a html, spaces must be converted to "%20".

Usage

make_url_friendly(input)

Arguments

Value

Character.

Map and rbind a list of data frames

Description

This function is a simple combination of purrr::map and purrr::reduce using rbind. This differs from purrr::map_dfr, which uses dplyr::map_dfr and therefore introduces dplyr as a dependency. If the provided list is empty, then an empty tibble will be returned.

Usage

map_and_rbind(.x, .f, ...)

Arguments

Value

A data frame or tibble.

Convert a single outlet to a tibble

Description

This function is designed to parse the content returned by the interior steps of the outlets and outlets_nearby functions.

Usage

outlet_to_tibble(outlet)

Arguments

Value

A tibble with the following columns:

• outlet_slid_spid

• outlet_name

• outlet_business

• outlet_latitude

• outlet_longitude

• outlet_suburb

• outlet_postcode

• outlet_business_hour_mon

• outlet_business_hour_tue

• outlet_business_hour_wed

• outlet_business_hour_thu

• outlet_business_hour_fri

• outlet_business_hour_sat

• outlet_business_hour_sun

• outlet_notes

Information for all outlets

Description

Information for all outlets

Usage

outlets(user_id = determine_user_id(), api_key = determine_api_key())

Arguments

Details

The outlet_name reported here is more accurately described as an outlet address. We keep the outlet_name column name as this is how the PTV API describes it.

The business hours are reported as characters. Usually they take on a format of "8.00AM - 10.00PM", but there variants such as "7.30AM - 11.00AM and 1.30PM - 6.00PM". For days on which an outlet is closed, the opening hours are usually reported as "CLOSED", but can also be an empty character. Some opening hours are "24 Hours". These fields are also filled with missing values and empty characters.

Value

A tibble with the following columns:

• outlet_slid_spid

• outlet_name

• outlet_business

• outlet_latitude

• outlet_longitude

• outlet_suburb

• outlet_postcode

• outlet_business_hour_mon

• outlet_business_hour_tue

• outlet_business_hour_wed

• outlet_business_hour_thu

• outlet_business_hour_fri

• outlet_business_hour_sat

• outlet_business_hour_sun

• outlet_notes

Examples

## Not run: 
outlets()

## End(Not run)

Information for outlets near a given location

Description

Information for outlets near a given location

Usage

outlets_nearby(
  latitude,
  longitude,
  max_distance = NULL,
  max_results = 30,
  user_id = determine_user_id(),
  api_key = determine_api_key()
)

Arguments

Details

The outlet_name reported here is more accurately described as an outlet address. We keep the outlet_name column name as this is how the PTV API describes it.

The business hours are reported as characters. Usually they take on a format of "8.00AM - 10.00PM", but there variants such as "7.30AM - 11.00AM and 1.30PM - 6.00PM". For days on which an outlet is closed, the opening hours are usually reported as "CLOSED", but can also be an empty character. Some opening hours are "24 Hours". These fields are also filled with missing values and empty characters.

Value

A tibble with the following columns:

• outlet_slid_spid

• outlet_name

• outlet_business

• outlet_latitude

• outlet_longitude

• outlet_suburb

• outlet_postcode

• outlet_business_hour_mon

• outlet_business_hour_tue

• outlet_business_hour_wed

• outlet_business_hour_thu

• outlet_business_hour_fri

• outlet_business_hour_sat

• outlet_business_hour_sun

• outlet_notes

Examples

## Not run: 
outlets_nearby(latitude = -37.8183, longitude = 144.9671)

## End(Not run)

Parse content of directions API call

Description

This function is designed to parse the content returned by the interior steps of the directions function.

Usage

parse_directions_content(directions_content)

Arguments

Value

A tibble consisting of the following columns:

• direction_id

• direction_name,

• route_id

• route_type

• route_type_description

• route_direction_description

Parse content of fare estimates API call

Description

This function is designed to parse the content returned by the interior steps of the fare_estimate function.

Usage

parse_fare_estimate_content(fare_estimate_content)

Arguments

Value

A data frame consisting of one row for each passenger_type, and the following columns:

• min_zone

• max_zone

• unique_zones

• early_bird

• free_tram_zone

• weekend_journey

• passenger_type

• fare_2_hour_peak

• fare_2_hour_off_peak

• fare_daily_peak

• fare_daily_off_peak

• pass_7_days

• pass_28_to_69_day_per_day

• pass_70_plus_day_per_day

• weekend_cap

• holiday_cap

Stopping pattern for a given run

Description

A pattern consists of all departures, stops, routes, runs, directions and disruptions associated with a particular run ID. This is returned as a list of tibbles, with output corresponding to their respective API calls.

Usage

patterns(
  run_ref,
  route_type,
  stop_id = NULL,
  departs = Sys.time(),
  user_id = determine_user_id(),
  api_key = determine_api_key()
)

Arguments

Details

The stops tibble has an output similar to that returned by stops_on_route. The routes tibble does not contain service status information.

Departures: The API seems to return the earliest 7 departures. While the PTV Timetable API supports filtering patterns by datetimes, the behaviour of this argument is not reliable — it appears to filter by day only, returning the earliest 7 departures of a different day. It is recommended that departures are retrieved via the departures function.

Value

An object of class "ptvapi", which is effectively a list with the following names:

• departures

• stops

• routes

• runs

• directions

• disruptions

Examples

## Not run: 
patterns(run_ref = "1", route_type = 0)
patterns(run_ref = "1", route_type = "Train")

## End(Not run)

Process a raw httr response and return an object of class ptv_api

Description

This S3 object returned by this function contains three elements:

• status_code, as an integer

• request, which is the request URL without authentication details

• content, the unparsed body of the response

Usage

process_response(response, request_url_without_auth)

Arguments

Value

An S3 object of class ptv_api

Use a character term to search for routes, stops, and outlets.

Description

There's only one search API call, and it covers stops, routes, and outlets. This function will return the response of this generic search. It is expected that other functions will take on of these three categories of search results, parse them, and return them to the user as a tibble.

Usage

ptv_search(
  search_term,
  latitude = NULL,
  longitude = NULL,
  max_distance = NULL,
  route_types = NULL,
  include_outlets = FALSE,
  match_stop_by_suburb = FALSE,
  match_route_by_suburb = FALSE,
  match_stop_by_gtfs_stop_id = FALSE,
  user_id = determine_user_id(),
  api_key = determine_api_key()
)

Arguments

Details

If the search term is numeric and/or less than 3 characters, the API will return only routes. By default, as little matching is done as possible, and as little as possible is returned. We rely on functions that call on this function to specify what is needed.

Value

The response of the search API call.

Information for a given route

Description

Information for a given route

Usage

route_information(
  route_id,
  include_geopath = FALSE,
  geopath_utc = NULL,
  user_id = determine_user_id(),
  api_key = determine_api_key()
)

Arguments

Value

A tibble of routes, with the following columns:

• route_id

• route_gtfs_id

• route_name

• route_type

• route_type_description

• route_number

• geopath

• service_status

• service_status_timestamp

Examples

## Not run: 
route_information(6)
route_information(6, include_geopath = TRUE)
route_information(6, include_geopath = TRUE, geopath_utc = "2020-07-01")

## End(Not run)

Convert a single route to a tibble

Description

This function is designed to parse the content returned by the interior steps of the routes function. Service status information may be NA, depending on the API call that was used to populate the information.

Usage

route_to_tibble(route)

Arguments

Value

A tibble of routes, with the following columns:

• route_id

• route_gtfs_id

• route_name

• route_type

• route_type_description

• route_number

• geopath

• service_status

• service_status_timestamp

Retrieve a translation from route type number to name

Description

Route types (tram, train, etc.) are provided to the PTV API as an integer code. This function retrieves a named vector in which the values are the route type descriptions, and the names of the vector are the route type numbers. Note that "Night Bus" is a separate route type.

Usage

route_types(user_id = determine_user_id(), api_key = determine_api_key())

Arguments

Value

A named integer vector in which the values are the route type descriptions, and the names of the vector are the route type numbers.

Examples

## Not run: 
route_types()

## End(Not run)

Information for all routes

Description

Information for all routes

Usage

routes(
  route_types = NULL,
  route_name = NULL,
  user_id = determine_user_id(),
  api_key = determine_api_key()
)

Arguments

Value

A tibble of routes, with the following columns:

• route_id

• route_gtfs_id

• route_name

• route_type

• route_type_description

• route_number

• geopath

• service_status

• service_status_timestamp

Examples

## Not run: 
routes()
routes(route_types = "Train")
routes(route_types = 0)
routes(route_types = c("Train", "Tram"))
routes(route_name = "Frankston")
routes(route_name = "Craigie")
routes(route_name = "werribee")

## End(Not run)

Information for a given run

Description

Run IDs are not unique across the network. If you are interested in a specific run, consider supplying a value to the optional route_type argument.

Usage

run_information(
  run_ref,
  route_type = NULL,
  include_geopath = FALSE,
  geopath_utc = NULL,
  date_utc = NULL,
  user_id = determine_user_id(),
  api_key = determine_api_key()
)

Arguments

Value

A tibble with the following columns:

• run_id (deprecated, use run_ref instead)

• run_ref

• route_id

• route_type

• route_type_description

• direction_id

• run_sequence

• final_stop_id

• destination_name

• status

• express_stop_count

• vehicle_position

• vehicle_descriptor

• geopath

Examples

## Not run: 
run_information("100")
run_information("100", include_geopath = TRUE)
run_information("100", include_geopath = TRUE, geopath_utc = "2020-07-01")
run_information("100", date_utc = "2020-07-01")

## End(Not run)

Convert a single run to a tibble

Description

This function is designed to parse the content returned by the interior steps of the runs_on_route and run_information functions.

Usage

run_to_tibble(run)

Arguments

Value

A tibble with the following columns:

• run_id (deprecated, use run_ref instead)

• run_ref

• route_id

• route_type

• route_type_description

• direction_id

• run_sequence

• final_stop_id

• destination_name

• status

• express_stop_count

• vehicle_position

• vehicle_descriptor

• geopath

Runs on a given route

Description

Runs on a given route

Usage

runs_on_route(
  route_id,
  route_type = NULL,
  date_utc = NULL,
  user_id = determine_user_id(),
  api_key = determine_api_key()
)

Arguments

Value

A tibble with the following columns:

• run_id (deprecated, use run_ref instead)

• run_ref

• route_id

• route_type

• route_type_description

• direction_id

• run_sequence

• final_stop_id

• destination_name

• status

• express_stop_count

• vehicle_position

• vehicle_descriptor

• geopath

Examples

## Not run: 
runs_on_route(6)
runs_on_route(6, route_type = "Train")
runs_on_route(6, route_type = 0)

## End(Not run)

Search for outlets using text

Description

This function will search outlets in which the search term can be found in either the outlet name, outlet business or outlet suburb. The search is case-insensitive. The search term must contain at least 3 characters, and cannot be numeric.

Usage

search_outlets(
  search_term,
  latitude = NULL,
  longitude = NULL,
  max_distance = NULL,
  route_types = NULL,
  user_id = determine_user_id(),
  api_key = determine_api_key()
)

Arguments

Value

A tibble with the following columns:

• outlet_slid_spid

• outlet_name

• outlet_business

• outlet_latitude

• outlet_longitude

• outlet_suburb

• outlet_postcode

• outlet_business_hour_mon

• outlet_business_hour_tue

• outlet_business_hour_wed

• outlet_business_hour_thu

• outlet_business_hour_fri

• outlet_business_hour_sat

• outlet_business_hour_sun

• outlet_notes

Examples

## Not run: 
search_outlets("St Kilda")
search_outlets("St Kilda", route_types = c("Train", "Tram"))
search_outlets("St Kilda", route_types = 1)

search_outlets(
  "St Kilda",
  latitude = -37.867647,
  longitude = 144.976809
)
search_outlets(
  "St Kilda",
  latitude = -37.867647,
  longitude = 144.976809,
  max_distance = 100
)

## End(Not run)

Search for routes using text

Description

This function will search routes in which the search term can be found in one of many fields, such as route_id, route_gtfs_id, or route_name. The search is case-insensitive. Unlike search_stops and search_outlets, this function supports searching for numerics, and has no minimum character requirement for search_term.

Usage

search_routes(
  search_term,
  latitude = NULL,
  longitude = NULL,
  max_distance = NULL,
  route_types = NULL,
  user_id = determine_user_id(),
  api_key = determine_api_key()
)

Arguments

Value

A tibble of routes, with the following columns:

• route_id

• route_gtfs_id

• route_name

• route_type

• route_type_description

• route_number

• geopath

• service_status

• service_status_timestamp

Examples

## Not run: 
search_routes("Pakenham")
search_routes("Pakenham", route_types = c("Train", "Tram"))
search_routes("Pakenham", route_types = 1)

search_routes(
  "Pakenham",
  latitude = -38.077877,
  longitude = 145.484751
)
search_routes(
  "Pakenham",
  latitude = -38.077877,
  longitude = 145.484751,
  max_distance = 100
)

## End(Not run)

Search for stops using text

Description

This function will search stops in which the search term can be found in either the stop name or the stop suburb. The search is case-insensitive. The search term must contain at least 3 characters, and cannot be numeric.

Usage

search_stops(
  search_term,
  latitude = NULL,
  longitude = NULL,
  max_distance = NULL,
  route_types = NULL,
  user_id = determine_user_id(),
  api_key = determine_api_key()
)

Arguments

Value

A tibble with the following columns:

• stop_id

• stop_name

• stop_suburb

• route_type

• route_type_description

• stop_sequence

• stop_latitude

• stop_longitude

• disruption_ids

Examples

## Not run: 
search_stops("Ascot Vale")
search_stops("Ascot Vale", route_types = c("Train", "Tram"))
search_stops("Ascot Vale", route_types = 1)

search_stops(
  "Ascot Vale",
  latitude = -37.774240,
  longitude = 144.915518
)
search_stops(
  "Ascot Vale",
  latitude = -37.774240,
  longitude = 144.915518,
  max_distance = 100
)

## End(Not run)

Information for a given stop (metropolitan and V/Line stations only)

Description

This function can be used when integer stop ID is already known. This can be searched for with either the stops_on_route or stops_nearby functions.

Usage

stop_information(
  stop_id,
  route_type,
  user_id = determine_user_id(),
  api_key = determine_api_key()
)

Arguments

Value

A single-row tibble with the following columns:

• stop_id

• stop_name

• route_type

• route_type_description

• station_details_id

• station_type

• station_description

• point_id

• mode_id

• operating_hours

• flexible_stop_opening_hours

• stop_contact

• stop_ticket

• stop_location

• stop_amenities

• stop_accessibility

• stop_staffing

• disruption_ids

Convert a single stop to a tibble

Description

This function is designed to parse the content returned by the interior steps of the stops_on_route and stops_nearby functions.

Usage

stop_to_tibble(stop)

Arguments

Value

A tibble with the following columns:

• stop_id

• stop_name

• stop_suburb

• route_type

• route_type_description

• stop_sequence

• stop_latitude

• stop_longitude

• disruption_ids

Stops near a given location

Description

Stops near a given location

Usage

stops_nearby(
  latitude,
  longitude,
  max_distance = NULL,
  route_types = NULL,
  user_id = determine_user_id(),
  api_key = determine_api_key()
)

Arguments

Value

A tibble with the following columns:

• stop_id

• stop_name

• stop_suburb

• route_type

• route_type_description

• stop_sequence

• stop_latitude

• stop_longitude

• disruption_ids

Examples

## Not run: 
stops_nearby(latitude = -37.8183, longitude = 144.9671)
stops_nearby(latitude = -37.8183, longitude = 144.9671, max_distance = 1000)
stops_nearby(
  latitude = -37.8183,
  longitude = 144.9671,
  route_types = c("Train", "Tram")
)

stops_nearby(
  latitude = -37.8183,
  longitude = 144.9671,
  route_types = 0
 )

## End(Not run)

Stops on a given route and route type

Description

Stops on a given route and route type

Usage

stops_on_route(
  route_id,
  route_type,
  direction_id = NULL,
  user_id = determine_user_id(),
  api_key = determine_api_key()
)

Arguments

Value

A tibble with the following columns:

• stop_id

• stop_name

• stop_suburb

• route_type

• route_type_description

• stop_sequence

• stop_latitude

• stop_longitude

• disruption_ids

Examples

## Not run: 
stops_on_route(6, route_type = "Train")
stops_on_route(6, route_type = 0)

## End(Not run)

Convert a POSIXct or character datetime to a format ready for a URL

Description

Datetimes accepted by the API need to be given in UTC. This function will accept a datetime or a character with a suitable datetime format, and output a character that is suitable for a URL. All URL input and output in this package should be in Melbourne time, and the UTC conversion should happen

Usage

to_datetime(datetime)

Arguments

Details

The API seems to accept both "%Y-%m-%dT%H:%M:%OS" and "%Y-%m-%d %H:%M:%OS", but we opt for the former.

Value

Character.

Strictly convert an object to an integer

Description

R does not have a built-in function to determine if a value is an integer (is.integer will check if the class of an object is "integer", but is.integer(3) will return FALSE). This helper function fills that gap. It will attempt to convert the input to an integer, but will error on any input that cannot be confidently expressed as an integer. It serves as a stricter version of as.integer. For example, the function will convert 3 or "3" to integers, but will error on 3.5 or "three".

Usage

to_integer(x)

Arguments

Value

An integer interpretation of x, if possible.

Translate a route type input into a numerical route type

Description

Many API calls require a route type (eg. "Tram" or "Train"). These must be provided as integers, which are translated to route type descriptions with the 'route_types() function/API call. This function will:

• Translate a case-insensitive description such as "Tram" or "Train" to the corresponding route type code

• Check a given integer to see if it is a valid route type code, returning it if so and erroring otherwise

• Return NULL on NULL input

This function is not vectorised.

Usage

translate_route_type(
  route_type,
  user_id = determine_user_id(),
  api_key = determine_api_key()
)

Arguments

Value

An integer route type code, or NULL if the input is NULL