Utility functions

Utility functions to aid the setup of local instances.

• get_instance checks for the existence of a mounted instance in the current session and returns it.

• ors_status returns the status reported by the ORS server.

• ors_ready checks if the mounted service is ready to use.

• get_profiles is a wrapper around get_status that returns the active profiles of the mounted service.

• any_mounted checks if an instance is mounted to the current session.

Usage

get_instance()

ors_status(url = NULL, force = TRUE)

get_profiles(url = NULL, force = TRUE)

ors_ready(url = NULL, force = TRUE, error = FALSE)

any_mounted()

Arguments

url

[character]

URL of an ORS server. Defaults to the the URL of the currently mounted ORS instance. This argument exists as a way to explicitly specify the URL to query in case the instance cannot easily be determined. For normal use, this argument should not need to be specfied.

force

[logical]

If TRUE, function must query server. If FALSE, the information will be read from the cache if possible. This argument is specially useful automated workflows where it is inconvenient to query the server unnecessarily often. Functions like ors_pairwise or ors_inspect generally do not force server requests for these functions in order to make subsequent calls faster. When running directly, this argument should stay TRUE to ensure the accuracy of the output.

error

[logical]

If TRUE, gives out an error if the service is not ready.

Value

get_instance returns an object of class ors_instance. ors_status returns a list of information on the running service. ors_ready returns a length-1 logical vector specifying if the service is running. get_profiles returns a vector containing the active profiles. any_mounted returns a length-1 logical.

Caching

The following functions make use of a runtime caching system: ors_ready(), ors_status(), get_profiles(), get_extract_boundaries(), ors_sample(). This means that, if force = FALSE, previously generated output is re-used instead of sending new requests. This can be particularly useful in automated workflows like loops where speed is important. When run directly, caching should not be necessary, which is why force = FALSE is the default of most of these functions (except get_extract_boundaries() because it deals with potentially much larger amounts of data).

"Runtime" in this context refers to the runtime of an ORS instance, i.e. the time after it is started. Cached results should only be valid for a specific runtime and discarded afterwards. When mounting a new instance different from the one mounted before, the runtime cache is cleared so that fresh requests must be made.

See also

ors_instance

Examples

# initialize an ORS instance
ors <- ors_instance(dir = tempdir(), dry = TRUE)
#> ℹ Downloading docker-compose.yml
#> ℹ Using OpenRouteService version v8.1.3
#> ✔ Downloaded docker-compose.yml [605ms]
#> 

# confirm that instance was mounted
any_mounted() # TRUE
#> [1] TRUE

# retrieve the instance object
get_instance()
#> <ORSInstance>
#>  server : http://localhost:8080/
#>  type   : local (docker)
#>  active : TRUE
#>  init   : FALSE

# check if the service is ready
ors_ready()
#> [1] FALSE

# assert the ready status
try(ors_ready(error = TRUE))
#> Error : Cannot reach the OpenRouteService server.
#> ℹ Did you start your local instance?

if (FALSE) { # \dontrun{
# the following functions require a running service
# retrieve a list of service options from the server
ors_status()

# retrieve a list of active profiles that can be used
get_profiles()
} # }