onemapsgapi (version 1.1.0)

get_travel: 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
)

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.

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.

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
if (FALSE) get_travel(token, sample[1:3, ],
    "start_lat", "start_lon", "end_lat", "end_lon",
    routes = c("cycle", "walk"))
if (FALSE) get_travel(token, sample[1:3, ],
    "start_lat", "start_lon", "end_lat", "end_lon",
    routes = c("drive", "pt"), pt_mode = c("bus", "transit"))

# no error, long format
if (FALSE) 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)

# no error, sf dataframe
if (FALSE) 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)

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