From ba153442bfcf52110c108785fe2426b81da219fd Mon Sep 17 00:00:00 2001 From: Joan Maspons Date: Fri, 15 Dec 2023 13:45:00 +0100 Subject: [PATCH] Updates after wiki updates FIX #6 --- R/changesets.R | 5 ++-- R/map_notes.R | 56 ++++++++++++++++++++++--------------- R/miscellaneous.R | 2 ++ man/osm_capabilities.Rd | 2 ++ man/osm_create_note.Rd | 3 +- man/osm_feed_notes.Rd | 5 +++- man/osm_query_changesets.Rd | 5 ++-- man/osm_search_notes.Rd | 39 +++++++++++++++----------- 8 files changed, 71 insertions(+), 46 deletions(-) diff --git a/R/changesets.R b/R/changesets.R index e85f9271..9ad8e66a 100644 --- a/R/changesets.R +++ b/R/changesets.R @@ -503,13 +503,12 @@ osm_download_changeset <- function(changeset_id, format = c("R", "xml")) { #' Modification and extension of the basic queries above may be required to support rollback and other uses we find for #' changesets. #' -#' This call returns at most 100 changesets matching criteria, it returns latest changesets +#' This call returns latest changesets matching criteria, #' [ordered by `created_at`](https://github.com/openstreetmap/openstreetmap-website/blob/f1c6a87aa137c11d0aff5a4b0e563ac2c2a8f82d/app/controllers/api/changesets_controller.rb#L174) #' – see the [current state](https://github.com/openstreetmap/openstreetmap-website/blob/master/app/controllers/api/changesets_controller.rb#L174). #' #' Te valid formats for `time` and `time_2` parameters are anything that -#' [this Ruby function](https://ruby-doc.org/3.2.2/exts/date/DateTime.html#method-c-parse) will parse. The default value -#' is `-4712-01-01T00:00:00+00:00`; this is Julian Day Number day 0. +#' [`Time.parse` Ruby function](https://ruby-doc.org/stdlib-2.7.0/libdoc/time/rdoc/Time.html#method-c-parse) will parse. #' #' @return #' @family get changesets' functions diff --git a/R/map_notes.R b/R/map_notes.R index 3c3d1161..29da329f 100644 --- a/R/map_notes.R +++ b/R/map_notes.R @@ -269,7 +269,8 @@ osm_read_note <- function(note_id, format = c("R", "xml", "rss", "json", "gpx")) #' @param authenticate If `TRUE` (default), the note is authored by the logged user. Otherwise, anonymous note. #' #' @details -#' If the request is made as an authenticated user, the note is associated to that user account. +#' If the request is made as an authenticated user, the note is associated to that user account. If the OAuth access +#' token used does not have the `allow_write_notes` permission, it is created as an anonymous note instead. #' #' @return #' @family edit notes' functions @@ -524,7 +525,7 @@ osm_delete_note <- function(note_id) { # | none, optional parameter # |- # |user -# | Same as display_name, but search based on user id instead of display name. When both options are provided, display_name takes priority. +# | Same as display_name, but search based on user id instead of display name. When both options are provided, display_name takes priority. # | Integer; User id # | none, optional parameter # |- @@ -570,40 +571,45 @@ osm_delete_note <- function(note_id) { #' Search for notes #' -#' Returns the existing notes matching either the initial note text or any of the comments. -#' -#' @param q Specifies the search query. -#' @param user Find notes by the user with the given user id (numeric) or display name (character). -#' @param from Specifies the beginning of a date range to search in for a note. A valid -#' [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) date. -#' @param to Specifies the end of a date range to search in for a note. A valid -#' [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) date. The date of today is the default. +#' Returns notes that match the specified query. If no query is provided, the most recently updated notes are returned. +#' +#' @param q Text search query, matching either note text or comments. +#' @param user Search for notes which the given user interacted with. The value can be the user id (`numeric`) or the +#' display name (`character`). +#' @param bbox Search area expressed as a string of coordinates of a valid bounding box (`left,bottom,right,top`) in +#' decimal degrees. Area must be at most 25 square degrees (see `osm_capabilities()$note_area` and +#' [this line in settings](https://github.com/openstreetmap/openstreetmap-website/blob/master/config/settings.yml#L27) +#' for the current value). +#' @param from Beginning date range for `created_at` or `updated_at` (specified by `sort`). Preferably in +#' [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) date format. +#' @param to End date range for `created_at` or `updated_at` (specified by `sort`). Preferably in +#' [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) date format. Only works when `from` is supplied. #' @param closed Specifies the number of days a note needs to be closed to no longer be returned. A value of 0 means #' only open notes are returned. A value of -1 means all notes are returned. 7 is the default. -#' @param sort Specifies the value which should be used to sort the notes. It is either possible to sort them by their -#' creation date (`created_at`) or the date of the last update (`updated_at`, the default). -#' @param order Specifies the order of the returned notes. It is possible to order them in ascending (`oldest`) or -#' descending (`newest`, the default) order. -#' @param limit Specifies the number of entries returned at max. A value of between 1 and 10000 is valid. 100 is the -#' default. +#' @param sort Sort results by creation (`created_at`) or update date (`updated_at`, the default). +#' @param order Sorting order. `oldest` is ascending order, `newest` is descending order (the default). +#' @param limit Maximum number of results between 1 and 10000 (may change, see `osm_capabilities()$api$notes` for the +#' current value). Default to 100. #' @param format Format of the the returned list of notes. Can be `R` (default), `xml`, `rss`, `json` or `gpx`. #' #' @details -#' The notes will be ordered by the date of their last change, the most recent one will be first. If no query was -#' specified, the latest notes are returned. +#' The notes will be ordered by the date of their last change, the most recent one will be first. #' #' @return #' @family get notes' functions #' @export #' #' @examples -#' notes <- osm_search_notes(q = "POI", from = "2017-10-01", to = "2017-10-27T15:27A", limit = 10) +#' notes <- osm_search_notes( +#' q = "POI", bbox = "0.1594133,40.5229822,3.3222508,42.8615226", +#' from = "2017-10-01", to = "2018-10-27T15:27A", limit = 10 +#' ) #' notes #' #' my_notes <- osm_search_notes(user = "jmaspons", closed = -1, format = "json") #' my_notes osm_search_notes <- function( - q, user, from, to, closed = 7, + q, user, bbox, from, to, closed = 7, sort = c("updated_at", "created_at"), order = c("newest", "oldest"), limit = 100, format = c("R", "xml", "rss", "json", "gpx")) { sort <- match.arg(sort) @@ -626,6 +632,9 @@ osm_search_notes <- function( } } + if (missing(bbox)) { + bbox <- NULL + } if (missing(from)) { from <- NULL } @@ -645,7 +654,7 @@ osm_search_notes <- function( req <- httr2::req_url_query( req, - q = q, user = user, display_name = display_name, + q = q, user = user, display_name = display_name, bbox = bbox, from = from, to = to, sort = sort, order = order, limit = limit ) @@ -688,7 +697,10 @@ osm_search_notes <- function( #' RSS Feed of notes in a bbox #' #' @param bbox Coordinates for the area to retrieve the notes from (`left,bottom,right,top`). Floating point numbers in -#' degrees, expressing a valid bounding box. +#' degrees, expressing a valid bounding box, not larger than the configured size limit, 25 square degrees (see +#' `osm_capabilities()$note_area` and +#' [this line in settings](https://github.com/openstreetmap/openstreetmap-website/blob/master/config/settings.yml#L27) +#' for the current value), not overlapping the dateline. #' #' @return #' @family get notes' functions diff --git a/R/miscellaneous.R b/R/miscellaneous.R index 25a65228..2db46995 100644 --- a/R/miscellaneous.R +++ b/R/miscellaneous.R @@ -120,6 +120,8 @@ osm_api_versions <- function() { #' in a changeset. #' * `changesets` `default_query_limit` and `maximum_query_limit` are the default and maximum values of the limit #' parameter of [osm_query_changesets()]. +#' * `notes` `default_query_limit` and `maximum_query_limit` are the default and maximum values of the limit parameter +#' of notes bounding box queries ([osm_read_bbox_notes()]) and search ([osm_search_notes()]). #' * The `status` element returns either _online_, _readonly_ or _offline_ for each of the database, API and GPX #' API. The `database` field is informational, and the `API`/`GPX-API` fields indicate whether a client should expect read #' and write requests to work (_online_), only read requests to work (_readonly_) or no requests to work (_offline_). diff --git a/man/osm_capabilities.Rd b/man/osm_capabilities.Rd index 4cf1f84c..7aa68962 100644 --- a/man/osm_capabilities.Rd +++ b/man/osm_capabilities.Rd @@ -24,6 +24,8 @@ API: in a changeset. \item \code{changesets} \code{default_query_limit} and \code{maximum_query_limit} are the default and maximum values of the limit parameter of \code{\link[=osm_query_changesets]{osm_query_changesets()}}. +\item \code{notes} \code{default_query_limit} and \code{maximum_query_limit} are the default and maximum values of the limit parameter +of notes bounding box queries (\code{\link[=osm_read_bbox_notes]{osm_read_bbox_notes()}}) and search (\code{\link[=osm_search_notes]{osm_search_notes()}}). \item The \code{status} element returns either \emph{online}, \emph{readonly} or \emph{offline} for each of the database, API and GPX API. The \code{database} field is informational, and the \code{API}/\code{GPX-API} fields indicate whether a client should expect read and write requests to work (\emph{online}), only read requests to work (\emph{readonly}) or no requests to work (\emph{offline}). diff --git a/man/osm_create_note.Rd b/man/osm_create_note.Rd index 70221481..2eb16e3d 100644 --- a/man/osm_create_note.Rd +++ b/man/osm_create_note.Rd @@ -19,7 +19,8 @@ osm_create_note(lat, lon, text, authenticate = TRUE) Create a new note } \details{ -If the request is made as an authenticated user, the note is associated to that user account. +If the request is made as an authenticated user, the note is associated to that user account. If the OAuth access +token used does not have the \code{allow_write_notes} permission, it is created as an anonymous note instead. } \seealso{ Other edit notes' functions: diff --git a/man/osm_feed_notes.Rd b/man/osm_feed_notes.Rd index 83ed3b00..51ea3434 100644 --- a/man/osm_feed_notes.Rd +++ b/man/osm_feed_notes.Rd @@ -8,7 +8,10 @@ osm_feed_notes(bbox) } \arguments{ \item{bbox}{Coordinates for the area to retrieve the notes from (\verb{left,bottom,right,top}). Floating point numbers in -degrees, expressing a valid bounding box.} +degrees, expressing a valid bounding box, not larger than the configured size limit, 25 square degrees (see +\code{osm_capabilities()$note_area} and +\href{https://github.com/openstreetmap/openstreetmap-website/blob/master/config/settings.yml#L27}{this line in settings} +for the current value), not overlapping the dateline.} } \description{ RSS Feed of notes in a bbox diff --git a/man/osm_query_changesets.Rd b/man/osm_query_changesets.Rd index 12c38d81..d4642166 100644 --- a/man/osm_query_changesets.Rd +++ b/man/osm_query_changesets.Rd @@ -54,13 +54,12 @@ returned document are the changesets and their tags. To get the full set of chan Modification and extension of the basic queries above may be required to support rollback and other uses we find for changesets. -This call returns at most 100 changesets matching criteria, it returns latest changesets +This call returns latest changesets matching criteria, \href{https://github.com/openstreetmap/openstreetmap-website/blob/f1c6a87aa137c11d0aff5a4b0e563ac2c2a8f82d/app/controllers/api/changesets_controller.rb#L174}{ordered by \code{created_at}} – see the \href{https://github.com/openstreetmap/openstreetmap-website/blob/master/app/controllers/api/changesets_controller.rb#L174}{current state}. Te valid formats for \code{time} and \code{time_2} parameters are anything that -\href{https://ruby-doc.org/3.2.2/exts/date/DateTime.html#method-c-parse}{this Ruby function} will parse. The default value -is \verb{-4712-01-01T00:00:00+00:00}; this is Julian Day Number day 0. +\href{https://ruby-doc.org/stdlib-2.7.0/libdoc/time/rdoc/Time.html#method-c-parse}{\code{Time.parse} Ruby function} will parse. } \examples{ \dontrun{ diff --git a/man/osm_search_notes.Rd b/man/osm_search_notes.Rd index fe97b067..b7f6779d 100644 --- a/man/osm_search_notes.Rd +++ b/man/osm_search_notes.Rd @@ -7,6 +7,7 @@ osm_search_notes( q, user, + bbox, from, to, closed = 7, @@ -17,39 +18,45 @@ osm_search_notes( ) } \arguments{ -\item{q}{Specifies the search query.} +\item{q}{Text search query, matching either note text or comments.} -\item{user}{Find notes by the user with the given user id (numeric) or display name (character).} +\item{user}{Search for notes which the given user interacted with. The value can be the user id (\code{numeric}) or the +display name (\code{character}).} -\item{from}{Specifies the beginning of a date range to search in for a note. A valid -\href{https://en.wikipedia.org/wiki/ISO_8601}{ISO 8601} date.} +\item{bbox}{Search area expressed as a string of coordinates of a valid bounding box (\verb{left,bottom,right,top}) in +decimal degrees. Area must be at most 25 square degrees (see \code{osm_capabilities()$note_area} and +\href{https://github.com/openstreetmap/openstreetmap-website/blob/master/config/settings.yml#L27}{this line in settings} +for the current value).} -\item{to}{Specifies the end of a date range to search in for a note. A valid -\href{https://en.wikipedia.org/wiki/ISO_8601}{ISO 8601} date. The date of today is the default.} +\item{from}{Beginning date range for \code{created_at} or \code{updated_at} (specified by \code{sort}). Preferably in +\href{https://en.wikipedia.org/wiki/ISO_8601}{ISO 8601} date format.} + +\item{to}{End date range for \code{created_at} or \code{updated_at} (specified by \code{sort}). Preferably in +\href{https://en.wikipedia.org/wiki/ISO_8601}{ISO 8601} date format. Only works when \code{from} is supplied.} \item{closed}{Specifies the number of days a note needs to be closed to no longer be returned. A value of 0 means only open notes are returned. A value of -1 means all notes are returned. 7 is the default.} -\item{sort}{Specifies the value which should be used to sort the notes. It is either possible to sort them by their -creation date (\code{created_at}) or the date of the last update (\code{updated_at}, the default).} +\item{sort}{Sort results by creation (\code{created_at}) or update date (\code{updated_at}, the default).} -\item{order}{Specifies the order of the returned notes. It is possible to order them in ascending (\code{oldest}) or -descending (\code{newest}, the default) order.} +\item{order}{Sorting order. \code{oldest} is ascending order, \code{newest} is descending order (the default).} -\item{limit}{Specifies the number of entries returned at max. A value of between 1 and 10000 is valid. 100 is the -default.} +\item{limit}{Maximum number of results between 1 and 10000 (may change, see \code{osm_capabilities()$api$notes} for the +current value). Default to 100.} \item{format}{Format of the the returned list of notes. Can be \code{R} (default), \code{xml}, \code{rss}, \code{json} or \code{gpx}.} } \description{ -Returns the existing notes matching either the initial note text or any of the comments. +Returns notes that match the specified query. If no query is provided, the most recently updated notes are returned. } \details{ -The notes will be ordered by the date of their last change, the most recent one will be first. If no query was -specified, the latest notes are returned. +The notes will be ordered by the date of their last change, the most recent one will be first. } \examples{ -notes <- osm_search_notes(q = "POI", from = "2017-10-01", to = "2017-10-27T15:27A", limit = 10) +notes <- osm_search_notes( + q = "POI", bbox = "0.1594133,40.5229822,3.3222508,42.8615226", + from = "2017-10-01", to = "2018-10-27T15:27A", limit = 10 +) notes my_notes <- osm_search_notes(user = "jmaspons", closed = -1, format = "json")