feat: Add snapping endpoint

DESCRIPTION

@@ -1,7 +1,7 @@
 Package: openrouteservice
 Title: Openrouteservice API Client
-Version: 0.4.2
-Authors@R: person("Andrzej", "Oleś", email = "andrzej@openrouteservice.org", comment = c(ORCID = "0000-0003-0285-2787"), role = c("aut", "cre"))
+Version: 0.5.0
+Authors@R: person("Andrzej", "Oleś", email = "andrzej.oles@gmail.com", comment = c(ORCID = "0000-0003-0285-2787"), role = c("aut", "cre"))
 Description: The package streamlines access to the services provided by openrouteservice.org.
   It allows you to painlessly query for directions, geocoding, isochrones, time-distance matrices, and POIs.
 URL: https://github.com/GIScience/openrouteservice-r
@@ -13,4 +13,4 @@ Encoding: UTF-8
 LazyData: true
 VignetteBuilder: knitr
 Roxygen: list(markdown = TRUE)
-RoxygenNote: 7.2.3
+RoxygenNote: 7.3.1

NAMESPACE

@@ -12,6 +12,7 @@ export(ors_matrix)
 export(ors_optimization)
 export(ors_pois)
 export(ors_profile)
+export(ors_snap)
 export(vehicles)
 importFrom(V8,v8)
 importFrom(geojsonsf,geojson_sf)

NEWS.md

@@ -1,3 +1,9 @@
+# openrouteservice 0.5.0
+
+## NEW FEATURES
+
+- Enable snap endpoint.
+
 # openrouteservice 0.4.0
 
 ## NEW FEATURES

R/api_call.R

@@ -82,7 +82,8 @@ ors_path <- function(endpoint) {
     geocode = "geocode",
     pois = "pois",
     elevation = "elevation",
-    optimization = "optimization"
+    optimization = "optimization",
+    snap = "v2/snap"
   )
   if (missing(endpoint))
     return(default_paths)

R/doc_utils.R

@@ -1,6 +1,6 @@
 doc_url <- function(service) {
   url_template <- switch(service,
-                         directions =, isochrones =, matrix = "https://openrouteservice.org/dev/#/api-docs/v2/%s/{profile}/post",
+                         directions =, isochrones =, matrix =, snap = "https://openrouteservice.org/dev/#/api-docs/v2/%s/{profile}/post",
                          pois =, optimization = "https://openrouteservice.org/dev/#/api-docs/%s/post",
                          "https://openrouteservice.org/dev/#/api-docs/%s")
   sprintf(url_template, service)

R/snap.R

@@ -0,0 +1,59 @@
+#' Openrouteservice Snapping
+#'
+#' Snap coordinates to road network
+#'
+#' @template param-coordinates
+#' @templateVar argname locations
+#' @template param-profile
+#' @param radius Maximum radius in meters around given coordinates to search for graph edges
+#' @param format Response format, defaults to `"geojson"`
+#' @template param-common
+#' @templateVar dotsargs parameters
+#' @templateVar endpoint snap
+#' @template return
+#' @templateVar return Coordinates of snapped location(s) and distance to the original point(s)
+#' @template return-text
+#' @template return-parsed
+#' @examples
+#' locations = list(
+#'   c(8.669629, 49.413025),
+#'   c(8.675841, 49.418532),
+#'   c(8.665144, 49.415594)
+#' )
+#'
+#' # query for duration and distance in km
+#' res = ors_snap(locations, radius = 350)
+#'
+#' @template author
+#' @export
+ors_snap <- function(locations,
+                     profile = ors_profile(),
+                     radius,
+                     format = c('geojson', 'json'),
+                     ...,
+                     api_key = ors_api_key(),
+                     output = c("parsed", "text")) {
+  ## required arguments with no default value
+  if (missing(locations))
+    stop('Missing argument "locations"')
+  if (missing(radius))
+    stop('Missing argument "radius"')
+
+  ## required arguments with defaults
+  profile <- match.arg(profile)
+  format <- match.arg(format)
+  output <- match.arg(output)
+
+  names(locations) <- NULL
+
+  ## request parameters
+  body <- list(locations = locations, radius = radius, ...)
+
+  api_call(
+    path = c("v2/snap", profile, format),
+    api_key = api_key,
+    body = body,
+    encode = "json",
+    output = output
+  )
+}

README.md

@@ -12,12 +12,13 @@ allows you to painlessly consume the following services:
 
 -   [directions](https://openrouteservice.org/dev/#/api-docs/v2/directions/%7Bprofile%7D/post)
     (routing)
--   [geocode](https://openrouteservice.org/dev/#/api-docs/geocode)
+-   [geocoding](https://openrouteservice.org/dev/#/api-docs/geocode)
     powered by [Pelias](https://pelias.io)
 -   [isochrones](https://openrouteservice.org/dev/#/api-docs/v2/isochrones/%7Bprofile%7D/post)
     (accessibility)
 -   time-distance
     [matrix](https://openrouteservice.org/dev/#/api-docs/v2/matrix/%7Bprofile%7D/post)
+-   [snapping](https://openrouteservice.org/dev/#/api-docs/snap) to ways
 -   [pois](https://openrouteservice.org/dev/#/api-docs/pois/post)
     (points of interest)
 -   SRTM
@@ -68,11 +69,18 @@ defaults are equivalent of having
                                           geocode = "geocode",
                                           pois = "pois",
                                           elevation = "elevation",
-                                          optimization = "optimization"))
+                                          optimization = "optimization",
+                                          snap = "v2/snap"))
 
 Package News
 ------------
 
+### version 0.5.0
+
+#### NEW FEATURES
+
+-   Enable snap endpoint.
+
 ### version 0.4.0
 
 #### NEW FEATURES
@@ -84,9 +92,3 @@ Package News
 #### BUG FIXES
 
 -   Fixed resolving of URL paths to endpoints.
-
-### version 0.3.2
-
-#### NEW FEATURES
-
--   More descriptive messages for API response errors.

man-roxygen/author.R

@@ -1 +1 @@
-#' @author Andrzej Oleś <andrzej@@openrouteservice.org>
+#' @author Andrzej Oleś <andrzej.oles@@gmail.com>

vignettes/openrouteservice.Rmd

@@ -32,9 +32,10 @@ doc <- openrouteservice:::doc_link
 to painlessly consume the following services:
 
   - `r doc('directions')` (routing)
-  - `r doc('geocode')` powered by [Pelias](https://pelias.io)
+  - `r doc('geocode', label='geocoding')` powered by [Pelias](https://pelias.io)
   - `r doc('isochrones')` (accessibility)
   - time-distance `r doc('matrix')`
+  - `r doc('snap', label='snapping')` to ways
   - `r doc('pois')` (points of interest)
   - SRTM `r doc('elevation')` for point and lines geometries
   - routing `r doc('optimization')` based on [Vroom](http://vroom-project.org/)