Check whether an OSRM server answers a routing request

Sends one small request to an Open Source Routing Machine (OSRM) server and reports whether the server answered it with HTTP status 200. cacs_isochrone() sends many requests for each site, so this shows beforehand whether the server can be reached and is accepting requests.

Usage

cacs_validate_osrm_endpoint(server = NULL, timeout = 5)

Arguments

server

A string giving the address of the OSRM server, or NULL (the default). With NULL or "", the address is the value of the option osrm.server at the time of the call, or the public OSRM demo server https://routing.openstreetmap.de/ when the option is not set. Loading the osrm package, for example with library(osrm), sets that option to the demo server and replaces a value set before (see the "OSRM servers" section of cacs_isochrone()). The option catchmentACS.osrm_docker_server is not used, so the local server that cacs_isochrone() uses with osrm_mode = "docker" is checked only when its address is given here.

timeout

A single positive number giving the number of seconds to wait for an answer; the default is 5.

Value

A tibble with one row and four columns:

endpoint

The server address used.

quota_ok

TRUE when the server answered with HTTP status 200, and FALSE otherwise, including when there was no answer.

response_ms

The time taken, in milliseconds, including any time spent waiting for an answer that did not come.

http_status

The HTTP status of the answer, as an integer, or NA when there was no answer.

Details

When the server answers with status 429, meaning that its limit on requests has been reached, the function gives a warning of class catchmentACS_warning_provider_quota_exhausted and still returns its result. Other statuses give no warning. A server that cannot be reached, or does not answer within timeout seconds, gives quota_ok = FALSE and http_status = NA without a warning or an error.

The request is for a route between two fixed points near Birmingham, Alabama, so a server whose map data do not cover them may not answer with status 200. It is sent to route/v1/driving/-86.8,33.5;-86.7,33.4 under the server address; on the public demo server, routed-car/, routed-bike/, or routed-foot/ comes first, following the option osrm.profile.

See also

Other validation and conditions: cacs_acs_validate(), cacs_capture_conditions(), cacs_validate_iso(), catchmentACS-conditions

Examples

# A local port where no server is expected to answer: quota_ok is FALSE
# and http_status is NA, without an error
cacs_validate_osrm_endpoint("http://localhost:9", timeout = 1)
#> # A tibble: 1 × 4
#>   endpoint           quota_ok response_ms http_status
#>   <chr>              <lgl>          <dbl>       <int>
#> 1 http://localhost:9 FALSE           9.80          NA

# Contacts the public OSRM demo server, which limits the requests it
# accepts, and then builds a drive-time area there.
if (FALSE) { # \dontrun{
site_07 <- data.frame(site_id = "AL_SITE_07", lon = -85.365, lat = 31.655)

# Check the server before building the drive-time areas
check <- cacs_validate_osrm_endpoint()
check
if (check$quota_ok) {
  iso <- cacs_isochrone(site_07, drive_times = 10)
} else if (identical(check$http_status, 429L)) {
  # Request limit reached: build the areas with a local OSRM server
  iso <- cacs_isochrone(site_07, drive_times = 10, osrm_mode = "docker")
} else {
  stop("The OSRM server is not accepting requests; see check$http_status.")
}
} # }