OpenRouteService instance

Creates an OpenRouteService instance object. An instance represents either a local/remote server or a directory from which OpenRouteService can be set up. Running this function or any of the related functions listed below stores the instance in an internal environment and enables functions interacting with the OpenRouteService API to automatically detect the appropriate server information needed to make a successful request. Hence, this function should always be run after loading rors as a means of fixing an instance to the current session.

While initializing an instance using an already running server requires no further action, this function family excels at building a local OpenRouteService server from source. Setting up a local server effectively removes any server-side rate limits and allows you to conveniently use the package functions on much larger datasets. For setting up a local server, it is required to build and start a Docker container. To do this, ors_instance starts Docker (if necessary), creates an ORS directory, parses all important information and jumpstarts a fresh ORS server.

For a full reference of the methods of an ORS instance, refer to ORSLocal and ORSRemote.

Usage

ors_instance(dir = ".", server = NULL, type = c("docker", "jar", "war"), ...)

Arguments

dir

[character]

Custom OpenRouteService directory. If not specified, the directory will be downloaded to the working direcotry. If a directory called "openrouteservice-{version}" is present, the download will be skipped unless overwrite is TRUE. Ignored if server is given.

server

[character]

URL of a server that accepts OpenRouteService requests. This can be a URL to a local or a remote server. The official public API can be accessed using the shortcuts "public" or "pub". Keep in mind that the public API is rate-restricted and requests are automatically throttled to 40 requests per minute. Routing functions will be slow for larger datasets.

type

[character]

The type of application to set up. Can be one of "docker" (default), "jar", or "war". Docker instances are the most versatile but also the most complex. Docker instances require Docker to be installed and accessible (relevant for Linux users). JAR instances require JDK >= 17 to be installed. WAR instances require Tomcat 10 to be installed. JAR instances are controlled using an external process and are thus bound to the R session. If the session dies, so do the OpenRouteService servers. Docker containers, conversely, are not bound to the R session. When using Docker Desktop (on Windows) and starting the Docker daemon from R, the software closes when R dies. This stops ORS containers but does not kill them.

...

Further arguments passed to ORSLocal or ORSRemote.

Value

R6 object of class ors_instance as created by ORSLocal or ORSRemote.

Session mounting

Upon initialization (or whenever calling a method) the object created by ors_instance mounts itself to the current R session. ors_* functions automatically identify the mounted ORS instance to retrieve important information for querying ORS servers or processing other data. Mounted instances are cleared when starting a new session or when overwriting with a new instance.

In case multiple instances are running simultaneously and should be queried in the same instance, ors_* functions allow to directly pass an instance object. Otherwise, it is recommended to implicitly use the mounted instance.

Examples

# \donttest{
# Download and furnish an ORS instance
# To execute this code, docker is required to be running
try(ors_instance(dir = tempdir(), version = "8.0.0"))
#> Docker version 26.1.3, build b72abbb
#> ℹ Downloading docker-compose.yml
#> ℹ Using OpenRouteService version v8.0.0
#> ✔ Downloaded docker-compose.yml [473ms]
#> 
#> <ORSInstance>
#>  server : http://localhost:8080/
#>  type   : local (docker)
#>  active : TRUE
#>  init   : FALSE

# Connect to the public API
Sys.setenv(ORS_TOKEN = "xxx") # a token must be set
ors_instance(server = "public")
#> <ORSInstance>
#>  server : https://api.openrouteservice.org/
#>  type   : remote 
#>  active : TRUE

# Connect to a local server
# Initializing an instance by passing the URL to a local server
# does not allow for control of the underlying data and
# configurations. If finer control over such things is needed,
# it is necessary to set up the instance from scratch using the
# `dir` argument.
ors_instance(server = "https://127.0.0.1:8001/")
#> <ORSInstance>
#>  server : https://127.0.0.1:8001/
#>  type   : remote 
#>  active : TRUE
# }