From d4caf50342135137fb2ca1ee6371a1e49d0daa83 Mon Sep 17 00:00:00 2001 From: aoles Date: Fri, 20 Sep 2024 22:25:10 +0200 Subject: [PATCH] feat: add export endpoint (closes #83) --- DESCRIPTION | 2 +- NAMESPACE | 1 + NEWS.md | 6 ++++ R/api_call.R | 3 +- R/doc_utils.R | 22 ++++++++++---- R/export.R | 50 ++++++++++++++++++++++++++++++++ README.Rmd | 2 +- README.md | 21 ++++++++------ man/ors_export.Rd | 52 ++++++++++++++++++++++++++++++++++ vignettes/openrouteservice.Rmd | 3 +- 10 files changed, 143 insertions(+), 19 deletions(-) create mode 100644 R/export.R create mode 100644 man/ors_export.Rd diff --git a/DESCRIPTION b/DESCRIPTION index 261b4f6..64f3f35 100755 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -1,6 +1,6 @@ Package: openrouteservice Title: Openrouteservice API Client -Version: 0.5.2 +Version: 0.6.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. diff --git a/NAMESPACE b/NAMESPACE index 308406f..dbcf8e6 100755 --- a/NAMESPACE +++ b/NAMESPACE @@ -6,6 +6,7 @@ export(jobs) export(ors_api_key) export(ors_directions) export(ors_elevation) +export(ors_export) export(ors_geocode) export(ors_isochrones) export(ors_matrix) diff --git a/NEWS.md b/NEWS.md index 4f14fce..4c53c18 100644 --- a/NEWS.md +++ b/NEWS.md @@ -1,3 +1,9 @@ +# openrouteservice 0.6.0 + +## NEW FEATURES + +- Enable export endpoint. + # openrouteservice 0.5.2 ## NEW FEATURES diff --git a/R/api_call.R b/R/api_call.R index 0086b28..603a13f 100755 --- a/R/api_call.R +++ b/R/api_call.R @@ -83,7 +83,8 @@ ors_path <- function(endpoint) { pois = "pois", elevation = "elevation", optimization = "optimization", - snap = "v2/snap" + snap = "v2/snap", + export = "v2/export" ) if (missing(endpoint)) return(default_paths) diff --git a/R/doc_utils.R b/R/doc_utils.R index 1c36328..7df0ff5 100755 --- a/R/doc_utils.R +++ b/R/doc_utils.R @@ -1,16 +1,26 @@ doc_url <- function(service) { - url_template <- switch(service, - 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") + url_template <- switch( + service, + directions = , + isochrones = , + matrix = , + snap = , + export = + "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) } -doc_link <- function(service, label=service) sprintf("[%s](%s)", label, doc_url(service)) +doc_link <- function(service, label = service) + sprintf("[%s](%s)", label, doc_url(service)) signup_url <- function (label) { url <- "https://openrouteservice.org/dev/#/signup" - if ( missing(label) ) + if (missing(label)) url else sprintf("[%s](%s)", label, url) diff --git a/R/export.R b/R/export.R new file mode 100644 index 0000000..b501911 --- /dev/null +++ b/R/export.R @@ -0,0 +1,50 @@ +#' Openrouteservice Export +#' +#' Export the base graph for different modes of transport. +#' +#' @template param-coordinates +#' @templateVar argname bbox +#' @templateVar suffix defining the SW and NE corners of a rectangular area of interest +#' @template param-profile +#' @template param-common +#' @templateVar dotsargs parameters +#' @templateVar endpoint export +#' @template return +#' @templateVar return Lists of graph nodes and edges contained in the provided bounding box and relevant for the given routing profile. The edge property `weight` represents travel time in seconds. The response is +#' @template return-text +#' @template return-parsed +#' @examples +#' \dontrun{ +#' bbox <- list( +#' c(8.681495, 49.41461), +#' c(8.686507, 49.41943) +#' ) +#' +#' res <- ors_export(bbox) +#' } +#' @template author +#' @export +ors_export <- function(bbox, + profile = ors_profile(), + ..., + api_key = ors_api_key(), + output = c("parsed", "text")) { + ## required arguments with no default value + if (missing(bbox)) + stop('Missing argument "bbox"') + + ## required arguments with defaults + profile <- match.arg(profile) + output <- match.arg(output) + + ## request parameters + body <- list(bbox = bbox, ...) + + api_call( + path = c("v2/export", profile), + api_key = api_key, + body = body, + encode = "json", + output = output + ) +} diff --git a/README.Rmd b/README.Rmd index 80962a0..001bc79 100644 --- a/README.Rmd +++ b/README.Rmd @@ -28,7 +28,7 @@ The default is to fire any requests against the free public services at instance, say a local one, set ```{r openrouteservice.url, eval=FALSE} -options(openrouteservice.url = "http://localhost:8080/ors") +options(openrouteservice.url = "http://localhost:8082/ors") ``` If necessary, endpoint configuration can be further customized through diff --git a/README.md b/README.md index 07fca15..00576f3 100644 --- a/README.md +++ b/README.md @@ -18,7 +18,9 @@ allows you to painlessly consume the following services: - time-distance [matrices](https://openrouteservice.org/dev/#/api-docs/v2/matrix/%7Bprofile%7D/post) - [snapping](https://openrouteservice.org/dev/#/api-docs/v2/snap/%7Bprofile%7D/post) - to ways + to OpenStreetMap ways +- [exporting](https://openrouteservice.org/dev/#/api-docs/v2/export/%7Bprofile%7D/post) + the underlying routing graph structure - [pois](https://openrouteservice.org/dev/#/api-docs/pois/post) (points of interest) - SRTM @@ -53,7 +55,7 @@ The default is to fire any requests against the free public services at <api.openrouteservice.org>. In order to query a different openrouteservice instance, say a local one, set - options(openrouteservice.url = "http://localhost:8080/ors") + options(openrouteservice.url = "http://localhost:8082/ors") If necessary, endpoint configuration can be further customized through `openrouteservice.paths` which specifies a named list of paths. The @@ -66,10 +68,17 @@ defaults are equivalent of having pois = "pois", elevation = "elevation", optimization = "optimization", - snap = "v2/snap")) + snap = "v2/snap", + export = "v2/export")) ## Package News +### version 0.6.0 + +#### NEW FEATURES + +- Enable export endpoint. + ### version 0.5.2 #### NEW FEATURES @@ -81,9 +90,3 @@ defaults are equivalent of having #### BUG FIXES - sf output for POIs endpoint (#81) - -### version 0.5.0 - -#### NEW FEATURES - -- Enable snap endpoint. diff --git a/man/ors_export.Rd b/man/ors_export.Rd new file mode 100644 index 0000000..67176b5 --- /dev/null +++ b/man/ors_export.Rd @@ -0,0 +1,52 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/export.R +\name{ors_export} +\alias{ors_export} +\title{Openrouteservice Export} +\usage{ +ors_export( + bbox, + profile = ors_profile(), + ..., + api_key = ors_api_key(), + output = c("parsed", "text") +) +} +\arguments{ +\item{bbox}{List of \verb{longitude, latitude} coordinate pairs defining the SW and NE corners of a rectangular area of interest, alternatively a two column \code{matrix} or \code{data.frame}.} + +\item{profile}{Route profile, defaults to \code{"driving-car"}.} + +\item{...}{Optional parameters as described \href{https://openrouteservice.org/dev/#/api-docs/v2/export/{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{ +Lists of graph nodes and edges contained in the provided bounding box and relevant for the given routing profile. The edge property \code{weight} represents travel time in seconds. The response is 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{ +Export the base graph for different modes of transport. +} +\examples{ +\dontrun{ +bbox <- list( + c(8.681495, 49.41461), + c(8.686507, 49.41943) +) + +res <- ors_export(bbox) +} +} +\author{ +Andrzej Oleś \href{mailto:andrzej.oles@gmail.com}{andrzej.oles@gmail.com} +} diff --git a/vignettes/openrouteservice.Rmd b/vignettes/openrouteservice.Rmd index c6615f8..bcc035c 100755 --- a/vignettes/openrouteservice.Rmd +++ b/vignettes/openrouteservice.Rmd @@ -35,7 +35,8 @@ to painlessly consume the following services: - `r doc('geocode', label='geocoding')` powered by [Pelias](https://pelias.io) - `r doc('isochrones')` (accessibility) - time-distance `r doc('matrix', label='matrices')` - - `r doc('snap', label='snapping')` to ways + - `r doc('snap', label='snapping')` to OpenStreetMap ways + - `r doc('export', label='exporting')` the underlying routing graph structure - `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/)