get_travel: Get Travel Time, Distance and Route

In onemapsgapi: R Wrapper for the 'OneMap.Sg API'

Get Travel Time, Distance and Route

Description

This function is a wrapper for the Route Service API. It takes in a dataframe of start and end coordinates and returns the same dataframe with total time, total distance and optionally route geometry. The function also accepts multiple arguments for 'route' and 'pt_mode', allowing users to compare various route options.

Note that if 'as_wide = TRUE' is selected, any columns with identical names as the additional output columns will be overwritten. Also, if as_wide = TRUE, only unique pairs of start and end points should be used. Regardless, using only unique pairs and joining data back is also a generally recommended workflow to reduce computation time.

Usage

get_travel(
  token,
  df,
  origin_lat,
  origin_lon,
  destination_lat,
  destination_lon,
  routes,
  date = Sys.Date(),
  time = format(Sys.time(), format = "%T"),
  pt_mode = "TRANSIT",
  pt_max_dist = NULL,
  as_wide = TRUE,
  parallel = FALSE,
  route_geom = FALSE
)

Arguments

token	User's API token. This can be retrieved using get_token
df	The input dataframe of start and end coordinates (the dataframe can have additional variables)
origin_lat	Name of the dataframe column with the start point latitude.
origin_lon	Name of the dataframe column with the start point longitude.
destination_lat	Name of the dataframe column with the end point latitude.
destination_lon	Name of the dataframe column with the end point longitude.
routes	Vector of the types of routes desired. Accepted values are walk, drive, pt (public transport), or cycle
date	Default = current date. Date for which route is requested.
time	Default = current time. Time for which route is requested.
pt_mode	Vector of public transport modes required. Default = route = c("transit"). Accepted values are transit, bus or rail
pt_max_dist	Optional if route = "pt". Maximum walking distance
as_wide	Default = TRUE. Whether to return output as a list as a long tibble with each row a route, or a wide tibble with the same number of rows as the input tibble.
parallel	Default = FALSE. Whether to run API calls in parallel or sequentially (default).
route_geom	Default = FALSE. Whether to return decoded route_geometry. Will only be returned if as_wide = FALSE. Please ensure packages googlePolylines and sf are installed and note that this is a lossy conversion.

Value

Original dataframe with total time and total distance for each route type.

If an error occurs, the output row will be have NAs for the additional variables, along with a warning message.

Examples

# sample dataframe
sample <- data.frame(start_lat = c(1.3746617, 1.3567797, 1.3361976, 500),
    start_lon = c(103.8366159, 103.9347695, 103.6957732, 501),
    end_lat = c(1.429443081, 1.380298287, 1.337586882, 601),
    end_lon = c(103.835005, 103.7452918, 103.6973215, 600),
    add_info = c("a", "b", "c", "d"))

# no error, wide format
## Not run: get_travel(token, sample[1:3, ],
    "start_lat", "start_lon", "end_lat", "end_lon",
    routes = c("cycle", "walk"))
## End(Not run)
## Not run: get_travel(token, sample[1:3, ],
    "start_lat", "start_lon", "end_lat", "end_lon",
    routes = c("drive", "pt"), pt_mode = c("bus", "transit"))
## End(Not run)

# no error, long format
## Not run: get_travel(token, sample[1:3, ],
    "start_lat", "start_lon", "end_lat", "end_lon",
    routes = c("walk", "pt"), pt_mode = c("bus", "transit"),
    as_wide = FALSE)
## End(Not run)

# no error, sf dataframe
## Not run: get_travel(token, sample[1:3, ],
    "start_lat", "start_lon", "end_lat", "end_lon",
    routes = c("drive", "pt"), pt_mode = c("bus", "transit"),
    as_wide = FALSE, route_geom = TRUE)
## End(Not run)

# with error
# warning message will show start/end/route/pt_mode for which an error occurred
## Not run: get_travel(token, sample,
    "start_lat", "start_lon", "end_lat", "end_lon",
    routes = c("cycle", "walk"))
## End(Not run)

onemapsgapi documentation built on Nov. 29, 2022, 9:06 a.m.