From 75563d74d6c930db0b4b1366b6ae906331012032 Mon Sep 17 00:00:00 2001 From: aoles Date: Fri, 24 May 2024 23:24:56 +0200 Subject: [PATCH] feat: add snapping endpoint --- DESCRIPTION | 6 ++-- NAMESPACE | 1 + NEWS.md | 6 ++++ R/api_call.R | 3 +- R/doc_utils.R | 2 +- R/snap.R | 59 ++++++++++++++++++++++++++++++++++ README.md | 18 ++++++----- man-roxygen/author.R | 2 +- man/fitBBox.Rd | 2 +- man/ors_api_key.Rd | 2 +- man/ors_directions.Rd | 2 +- man/ors_elevation.Rd | 2 +- man/ors_geocode.Rd | 2 +- man/ors_isochrones.Rd | 2 +- man/ors_matrix.Rd | 2 +- man/ors_optimization.Rd | 2 +- man/ors_pois.Rd | 2 +- man/ors_profile.Rd | 2 +- man/ors_snap.Rd | 59 ++++++++++++++++++++++++++++++++++ vignettes/openrouteservice.Rmd | 3 +- 20 files changed, 154 insertions(+), 25 deletions(-) create mode 100644 R/snap.R create mode 100644 man/ors_snap.Rd diff --git a/DESCRIPTION b/DESCRIPTION index d567f4f..cb6ce9f 100755 --- a/DESCRIPTION +++ b/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 diff --git a/NAMESPACE b/NAMESPACE index 28b37e5..7429d11 100755 --- a/NAMESPACE +++ b/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) diff --git a/NEWS.md b/NEWS.md index d05117e..f109fa4 100644 --- a/NEWS.md +++ b/NEWS.md @@ -1,3 +1,9 @@ +# openrouteservice 0.5.0 + +## NEW FEATURES + +- Enable snap endpoint. + # openrouteservice 0.4.0 ## NEW FEATURES diff --git a/R/api_call.R b/R/api_call.R index 925c312..611f440 100755 --- a/R/api_call.R +++ b/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) diff --git a/R/doc_utils.R b/R/doc_utils.R index e32e331..1c36328 100755 --- a/R/doc_utils.R +++ b/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) diff --git a/R/snap.R b/R/snap.R new file mode 100644 index 0000000..98ba183 --- /dev/null +++ b/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 + ) +} diff --git a/README.md b/README.md index 1e0a2d0..1246b27 100644 --- a/README.md +++ b/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. diff --git a/man-roxygen/author.R b/man-roxygen/author.R index 68233ce..971bbe5 100755 --- a/man-roxygen/author.R +++ b/man-roxygen/author.R @@ -1 +1 @@ -#' @author Andrzej Oleś +#' @author Andrzej Oleś diff --git a/man/fitBBox.Rd b/man/fitBBox.Rd index f8afd45..6d73514 100755 --- a/man/fitBBox.Rd +++ b/man/fitBBox.Rd @@ -19,5 +19,5 @@ The modified map widget. Helper function to set the bounds of a leaflet map widget. } \author{ -Andrzej Oleś \href{mailto:andrzej@openrouteservice.org}{andrzej@openrouteservice.org} +Andrzej Oleś \href{mailto:andrzej.oles@gmail.com}{andrzej.oles@gmail.com} } diff --git a/man/ors_api_key.Rd b/man/ors_api_key.Rd index 6a1236e..9511f0e 100755 --- a/man/ors_api_key.Rd +++ b/man/ors_api_key.Rd @@ -41,5 +41,5 @@ openrouteservice api key can be overridden by specifying it in \code{options("openrouteservice.api_key_env")}. } \author{ -Andrzej Oleś \href{mailto:andrzej@openrouteservice.org}{andrzej@openrouteservice.org} +Andrzej Oleś \href{mailto:andrzej.oles@gmail.com}{andrzej.oles@gmail.com} } diff --git a/man/ors_directions.Rd b/man/ors_directions.Rd index 4ee7927..e2ef0e1 100755 --- a/man/ors_directions.Rd +++ b/man/ors_directions.Rd @@ -59,5 +59,5 @@ locations <- data.frame(lng = c(8.34234, 8.327807, 8.34423), ors_directions(locations, output = "sf") } \author{ -Andrzej Oleś \href{mailto:andrzej@openrouteservice.org}{andrzej@openrouteservice.org} +Andrzej Oleś \href{mailto:andrzej.oles@gmail.com}{andrzej.oles@gmail.com} } diff --git a/man/ors_elevation.Rd b/man/ors_elevation.Rd index 40fd724..7666f14 100644 --- a/man/ors_elevation.Rd +++ b/man/ors_elevation.Rd @@ -67,5 +67,5 @@ ors_elevation("polyline", coordinates, format_out = "encodedpolyline") } \author{ -Andrzej Oleś \href{mailto:andrzej@openrouteservice.org}{andrzej@openrouteservice.org} +Andrzej Oleś \href{mailto:andrzej.oles@gmail.com}{andrzej.oles@gmail.com} } diff --git a/man/ors_geocode.Rd b/man/ors_geocode.Rd index 112d76c..d6aec19 100755 --- a/man/ors_geocode.Rd +++ b/man/ors_geocode.Rd @@ -59,5 +59,5 @@ y = ors_geocode(location = location, layers = "locality", size = 1) } \author{ -Andrzej Oleś \href{mailto:andrzej@openrouteservice.org}{andrzej@openrouteservice.org} +Andrzej Oleś \href{mailto:andrzej.oles@gmail.com}{andrzej.oles@gmail.com} } diff --git a/man/ors_isochrones.Rd b/man/ors_isochrones.Rd index 278164e..5f37068 100755 --- a/man/ors_isochrones.Rd +++ b/man/ors_isochrones.Rd @@ -58,5 +58,5 @@ locations <- list(c(8.681495, 49.41461), c(8.686507,49.41943)) ors_isochrones(locations, range=c(300, 200)) } \author{ -Andrzej Oleś \href{mailto:andrzej@openrouteservice.org}{andrzej@openrouteservice.org} +Andrzej Oleś \href{mailto:andrzej.oles@gmail.com}{andrzej.oles@gmail.com} } diff --git a/man/ors_matrix.Rd b/man/ors_matrix.Rd index d0e79e3..a6e5289 100755 --- a/man/ors_matrix.Rd +++ b/man/ors_matrix.Rd @@ -56,5 +56,5 @@ res$durations / 3600 res$distances } \author{ -Andrzej Oleś \href{mailto:andrzej@openrouteservice.org}{andrzej@openrouteservice.org} +Andrzej Oleś \href{mailto:andrzej.oles@gmail.com}{andrzej.oles@gmail.com} } diff --git a/man/ors_optimization.Rd b/man/ors_optimization.Rd index 2c6867b..c8dab1a 100644 --- a/man/ors_optimization.Rd +++ b/man/ors_optimization.Rd @@ -137,5 +137,5 @@ jobs = jobs( ors_optimization(jobs, vehicles) } \author{ -Andrzej Oleś \href{mailto:andrzej@openrouteservice.org}{andrzej@openrouteservice.org} +Andrzej Oleś \href{mailto:andrzej.oles@gmail.com}{andrzej.oles@gmail.com} } diff --git a/man/ors_pois.Rd b/man/ors_pois.Rd index c375217..3168ab3 100755 --- a/man/ors_pois.Rd +++ b/man/ors_pois.Rd @@ -83,5 +83,5 @@ ors_pois(geometry = geometry, ors_pois("stats", geometry = geometry) } \author{ -Andrzej Oleś \href{mailto:andrzej@openrouteservice.org}{andrzej@openrouteservice.org} +Andrzej Oleś \href{mailto:andrzej.oles@gmail.com}{andrzej.oles@gmail.com} } diff --git a/man/ors_profile.Rd b/man/ors_profile.Rd index a50c222..e9613de 100644 --- a/man/ors_profile.Rd +++ b/man/ors_profile.Rd @@ -33,5 +33,5 @@ ors_profile("car") \code{\link[=ors_directions]{ors_directions()}}, \code{\link[=ors_isochrones]{ors_isochrones()}}, \code{\link[=ors_matrix]{ors_matrix()}} } \author{ -Andrzej Oleś \href{mailto:andrzej@openrouteservice.org}{andrzej@openrouteservice.org} +Andrzej Oleś \href{mailto:andrzej.oles@gmail.com}{andrzej.oles@gmail.com} } diff --git a/man/ors_snap.Rd b/man/ors_snap.Rd new file mode 100644 index 0000000..e4f7513 --- /dev/null +++ b/man/ors_snap.Rd @@ -0,0 +1,59 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/snap.R +\name{ors_snap} +\alias{ors_snap} +\title{Openrouteservice Snapping} +\usage{ +ors_snap( + locations, + profile = ors_profile(), + radius, + format = c("geojson", "json"), + ..., + api_key = ors_api_key(), + output = c("parsed", "text") +) +} +\arguments{ +\item{locations}{List of \verb{longitude, latitude} coordinate pairs, alternatively a two column \code{matrix} or \code{data.frame}.} + +\item{profile}{Route profile, defaults to \code{"driving-car"}.} + +\item{radius}{Maximum radius in meters around given coordinates to search for graph edges} + +\item{format}{Response format, defaults to \code{"geojson"}} + +\item{...}{Optional parameters as described \href{https://openrouteservice.org/dev/#/api-docs/v2/snap/{profile}/post}{here}} + +\item{api_key}{Character scalar containing openrouteservice API key} + +\item{output}{Output format. By default the response is being parsed to a list-based R object} +} +\value{ +Coordinates of snapped location(s) and distance to the original point(s) structured according to \code{output}: + +\itemize{ +\item for \code{"text"}, a character vector of length 1 re-encoded to UTF-8. +} + +\itemize{ +\item for \code{"parsed"}, a parsed R object. +} +} +\description{ +Snap coordinates to road network +} +\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) + +} +\author{ +Andrzej Oleś \href{mailto:andrzej.oles@gmail.com}{andrzej.oles@gmail.com} +} diff --git a/vignettes/openrouteservice.Rmd b/vignettes/openrouteservice.Rmd index 90f699a..76a2d8f 100755 --- a/vignettes/openrouteservice.Rmd +++ b/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/)