Skip to contents

Route inspection

Source: R/inspect.R
ors_inspect.Rd

Calls the directions service once to get a closer look at route characteristics and attributes. Produces a dataframe containing an elaborate perspective on route sections and their contextual properties. ors_inspect can also be used as a relatively low-level interface to the directions service with the ability to return responses as parsed or unparsed JSONs.

The summary function computes summary statistics and interval tables for a given route.

Usage

ors_inspect(
  src,
  profile = NULL,
  level = c("waypoint", "step", "segment"),
  attributes = NULL,
  extra_info = NULL,
  elevation = TRUE,
  navigation = FALSE,
  alternative_routes = NULL,
  round_trip = NULL,
  as = c("tidy", "list", "string"),
  elev_as_z = FALSE,
  instance = NULL,
  ...,
  params = NULL
)

# S3 method for class 'ors_route'
summary(object, ...)

Arguments

src

[sf]

Source dataset containing at least two point geometries for which routes are to be computed. If round_trip is specified, source must contain a single coordinate pair from which a round trip is generated.

profile

[character]

Means of transport as supported by OpenRouteService. Defaults to the first profile in a call to get_profiles. For ors_shortest_distances, profile can be a character vector, for all other functions it needs to be a character scalar. For details on all profiles, refer to the backend reference.

level

[character]

Level of route aggregation. Must be one of waypoint, step or segment. See details.

attributes

[list]

List of attributes that summarize route characteristics. This includes three values: avgspeed states the average vehicle speed along the route, detourfactor indicates how much the route deviates from a straight line. percentage shows the share of a segment compared to the entire route. If TRUE, all values are included.

extra_info

[character]/[TRUE]

List of keywords that add extra information regarding each linestring segment of the output. If TRUE, all values are included. See details for more information.

elevation

[logical]

If TRUE, elevation data is included in the output.

navigation

[logical]

If TRUE, navigation information is included in the output, i.e., instructions and road exits. If level == "segment", navigation data is dropped from the output.

alternative_routes

[list]

Named list that specifies options for alternative routes and accepts up to three parameters. target_count is the maximum number of routes to compute (including the recommended route). Must be an integer between 1 and 3 and defaults to 1. The output can contain less routes than specified if no other alternatives can be computed from the src coordinates. share_factor denotes the maximum share of identical paths between routes. weight_factor is the maximum factor that a route can deviate (i.e. be longer) from the original route. If specified, and target_count is larger than 1, the output is wrapped in a list of up to three dataframes. If NULL, no alternative routes are computed.

round_trip

[list]

Named list that specifies options for round trips and accepts up to three parameters. length is the approximate length of the round trip. points denotes the number of route points from which to derive a round trip (the higher the rounder). seed controls the randomisation of the route direction. If specified, src must contain a single coordinate pair from which a round trip is to be generated. If NULL, no round trip is computed.

as

[character]

How to format the output. If "string", returns the entire JSON response string. If "list", returns a parsed JSON list. If "tidy", performs lots of data preparation to shape the response into a tibble.

elev_as_z

[logical]

If TRUE, elevation data is stored as z-values in the geometry of the output sf dataframe. If FALSE, elevation is stored as a distinct dataframe column. Ignored if elevation = FALSE.

instance

[ors_instance]

Object of an OpenRouteService instance that should be used for route computations. It is recommended to use ors_instance to set an instance globally. This argument should only be used if activating an instance globally is not feasible.

...

Additional arguments passed to the ORS API. Convenience way to directly pass arguments of ors_params.

params

List of additional arguments passed to the ORS API. See ors_params for details.

object

A route object of class ors_inspect.

Value

Returns an sf dataframe containing detailed sections of all routes between the coordinates specified in src, aggregated according to the level of aggregation stated in level. If alternative_routes is specified, returns a list of sf dataframes instead with each element containing a route alternative.

Details

OpenRouteService distinguishes between three types of route aggregation: Segments, steps and waypoints. A segment is a single route between src[i, ] and src[i + 1, ]. A step is a route section as relevant for a navigation system. A waypoint is a straight connection between two geographical points on a route.

Depending on the chosen level of aggregation, the output has to be adjusted through interpolation and aggregation. For all levels below "segment", ORS attributes are stored as R attributes and are not included in the dataframe. For "waypoint", distances and durations are derived from the geometry lengths and do not take into account elevation (due to restrictions in the s2 package). Extra information (using the extra_info argument) and street names do not perfectly overlap with steps and segments. In these cases, the value with the highest overlap is adopted causing some information loss. Navigation information is dropped on "segment" level. In order to establish this structure, ors_inspect depends on the navigation parameter and forces it to be TRUE. When navigation is FALSE, ORS omits steps - and hence also waypoints

  • from the response.

Extra information can be requested as additional context for each waypoint on a route. Possible values include:

steepness

Ordered factor describing how steep a part of a route is.

suitability

Ordinal numeric describing how suitable a part of a route is (1 - unsuitable; 10 - suitable).

surface

Unordered factor describing the surface material covering a part of a route.

waycategory

Unordered factor describing special parts of a route.

waytype

Unordered factor containing different types of roads.

tollways

For driving-* profiles, specifies whether a part of a route is a tollway.

traildifficulty

For walking and driving profiles, specifies the OSM trail difficulty.

osmid

For the wheelchair profile, contains the OSM IDs of used ways.

roadaccessrestrictions

Unordered factor describing road access restriction.

countryinfo

Nominal numeric containing country codes of a part of a route.

green

For walking profiles, describes the amount of green on a route (1 - little; 10 - much).

noise

For walking profiles, describes the amount of noise on a route (1 - little; 10 - much).

See also

ors_pairwise, plot_section

Examples

if (FALSE) { # \dontrun{
sample_source <- ors_sample(1)
sample_dest <- ors_sample(1)
profile <- get_profiles()[1]

# Basic inspection without extra information
insp <- ors_inspect(sample_source, sample_dest, profile)

# Advanced inspection with extra information
insp_adv <- ors_inspect(
  sample_source,
  sample_dest,
  profile,
  extra_info = TRUE
)

# Inspection of route elevation data
insp_elev <- ors_inspect(
  sample_source,
  sample_dest,
  profile,
  elevation = TRUE,
  elev_as_z = FALSE
)

# Inspection of route summary attributes
insp_attr <- ors_inspect(
  sample_source,
  sample_dest,
  profile,
  attributes = "detourfactor"
)
attr(insp_attr, "detourfactor")

# Altering the route by passing further arguments
insp_opts <- ors_inspect(
  sample_source,
  sample_dest,
  profile,
  continue_straight = TRUE,
  preference = "shortest",
  maximum_speed = 80
)

# Summarizing route specifics
route_summary <- summary(insp_adv)
} # }