Update roxygen documenting server side changes

Updates don't require client side changes
ropensci · Nov 17, 2024 · 9524254 · 9524254
1 parent f84cf74
commit 9524254
Show file tree

Hide file tree

Showing 14 changed files with 281 additions and 205 deletions.
diff --git a/DESCRIPTION b/DESCRIPTION
@@ -1,7 +1,7 @@
 Type: Package
 Package: osmapiR
 Title: 'OpenStreetMap' API
-Version: 0.2.1.9001
+Version: 0.2.1.9002
 Authors@R: c(
     person("Joan", "Maspons", , "[email protected]", role = c("aut", "cre", "cph"),
            comment = c(ORCID = "0000-0003-2286-8727")),
@@ -33,7 +33,7 @@ VignetteBuilder:
 Config/testthat/edition: 3
 Encoding: UTF-8
 Roxygen: list(markdown = TRUE)
-RoxygenNote: 7.3.1
-OSMWikiVersion: 2711808
+RoxygenNote: 7.3.2
+OSMWikiVersion: 2775892
 X-schema.org-keywords: open street map, openstreetmap, OSM,
     openstreetmap-api, osmapi, API
diff --git a/NEWS.md b/NEWS.md
@@ -1,6 +1,7 @@
 # osmapiR (development version)
 
 * Use the new function `httr2::oauth_cache_clear()` from httr2 1.0.6 (#58 by @hadley).
+* Update documentation and code for server-side changes documented in OSMWikiVersion 2775892 (#60).
 
 # osmapiR 0.2.1
 

diff --git a/R/osm_get_changesets.R b/R/osm_get_changesets.R
@@ -26,48 +26,66 @@
 #' ## `format = "xml"`
 #' Returns a [xml2::xml_document-class] with the following format:
 #' ``` xml
-#' <osm>
-#' 	<changeset id="10" created_at="2008-11-08T19:07:39+01:00" open="true" user="fred" uid="123" min_lon="7.0191821" min_lat="49.2785426" max_lon="7.0197485" max_lat="49.2793101" comments_count="3" changes_count="10">
-#' 		<tag k="created_by" v="JOSM 1.61"/>
-#' 		<tag k="comment" v="Just adding some streetnames"/>
-#' 		...
-#' 		<discussion>
-#' 			<comment date="2015-01-01T18:56:48Z" uid="1841" user="metaodi">
-#' 				<text>Did you verify those street names?</text>
-#' 			</comment>
-#' 			<comment date="2015-01-01T18:58:03Z" uid="123" user="fred">
-#' 				<text>sure!</text>
-#' 			</comment>
-#' 			...
-#' 		</discussion>
-#' 	</changeset>
-#' 	<changeset>
-#' 	  ...
-#' 	</changeset>
+#' <osm version="0.6" generator="CGImap 0.9.3 (987909 spike-08.openstreetmap.org)" copyright="OpenStreetMap and contributors" attribution="http://www.openstreetmap.org/copyright" license="http://opendatacommons.org/licenses/odbl/1-0/">
+#'   <changeset id="10" created_at="2008-11-08T19:07:39+01:00" open="true" user="fred" uid="123" min_lon="7.0191821" min_lat="49.2785426" max_lon="7.0197485" max_lat="49.2793101" comments_count="3" changes_count="10">
+#'     <tag k="created_by" v="JOSM 1.61"/>
+#'     <tag k="comment" v="Just adding some streetnames"/>
+#'     ...
+#'     <discussion>
+#'       <comment id="1234" date="2015-01-01T18:56:48Z" uid="1841" user="metaodi">
+#'         <text>Did you verify those street names?</text>
+#'       </comment>
+#'       <comment id="5678" date="2015-01-01T18:58:03Z" uid="123" user="fred">
+#'         <text>sure!</text>
+#'       </comment>
+#'       ...
+#'     </discussion>
+#'   </changeset>
+#'   <changeset>
+#'     ...
+#'   </changeset>
 #' </osm>
 #' ```
 #'
 #' ## `format = "json"`
+#' *Please note that the JSON format has changed on August 25, 2024 with the release of openstreetmap-cgimap 2.0.0, to*
+#' *align it with the existing Rails format.*
+#'
 #' Returns a list with the following json structure:
 #' ``` json
 #' {
-#'  "version": "0.6",
-#'  "elements": [
-#'   {"type": "changeset",
-#'    "id": 10,
-#'    "created_at": "2005-05-01T16:09:37Z",
-#'    "closed_at": "2005-05-01T17:16:44Z",
-#'    "open": False,
-#'    "user": "Petter Reinholdtsen",
-#'    "uid": 24,
-#'    "minlat": 59.9513092,
-#'    "minlon": 10.7719727,
-#'    "maxlat": 59.9561501,
-#'    "maxlon": 10.7994537,
-#'    "comments_count": 1,
-#'    "changes_count": 10,
-#'    "discussion": [{"date": "2022-03-22T20:58:30Z", "uid": 15079200, "user": "Ethan White of Cheriton", "text": "wow no one have said anything here 3/22/2022\n"}]
-#'   }, ...]
+#'   "version": "0.6",
+#'   "generator": "openstreetmap-cgimap 2.0.0 (4003517 spike-08.openstreetmap.org)",
+#'   "copyright": "OpenStreetMap and contributors",
+#'   "attribution": "http://www.openstreetmap.org/copyright",
+#'   "license": "http://opendatacommons.org/licenses/odbl/1-0/",
+#'   "changeset": [
+#'     {
+#'       "id": 10,
+#'       "created_at": "2005-05-01T16:09:37Z",
+#'       "open": false,
+#'       "comments_count": 1,
+#'       "changes_count": 10,
+#'       "closed_at": "2005-05-01T17:16:44Z",
+#'       "min_lat": 59.9513092,
+#'       "min_lon": 10.7719727,
+#'       "max_lat": 59.9561501,
+#'       "max_lon": 10.7994537,
+#'       "uid": 24,
+#'       "user": "Petter Reinholdtsen",
+#'       "comments": [
+#'         {
+#'           "id": 836447,
+#'           "visible": true,
+#'           "date": "2022-03-22T20:58:30Z",
+#'           "uid": 15079200,
+#'           "user": "Ethan White of Cheriton",
+#'           "text": "wow no one have said anything here 3/22/2022\n"
+#'         }
+#'       ]
+#'     },
+#'     ...
+#'   ]
 #' }
 #' ```
 #'

diff --git a/R/osm_query_changesets.R b/R/osm_query_changesets.R
@@ -42,48 +42,51 @@
 #' ## `format = "xml"`
 #' Returns a [xml2::xml_document-class] with the following format:
 #' ``` xml
-#' <osm>
-#' 	<changeset id="10" created_at="2008-11-08T19:07:39+01:00" open="true" user="fred" uid="123" min_lon="7.0191821" min_lat="49.2785426" max_lon="7.0197485" max_lat="49.2793101" comments_count="3" changes_count="10">
-#' 		<tag k="created_by" v="JOSM 1.61"/>
-#' 		<tag k="comment" v="Just adding some streetnames"/>
-#' 		...
-#' 		<discussion>
-#' 			<comment date="2015-01-01T18:56:48Z" uid="1841" user="metaodi">
-#' 				<text>Did you verify those street names?</text>
-#' 			</comment>
-#' 			<comment date="2015-01-01T18:58:03Z" uid="123" user="fred">
-#' 				<text>sure!</text>
-#' 			</comment>
-#' 			...
-#' 		</discussion>
-#' 	</changeset>
-#' 	<changeset ...>
-#' 	  ...
-#' 	</changeset>
+#' <osm version="0.6" generator="OpenStreetMap server" copyright="OpenStreetMap and contributors" attribution="http://www.openstreetmap.org/copyright" license="http://opendatacommons.org/licenses/odbl/1-0/">
+#'   <changeset id="10" created_at="2005-05-01T16:09:37Z" open="false" comments_count="1" changes_count="10" closed_at="2005-05-01T17:16:44Z" min_lat="59.9513092" min_lon="10.7719727" max_lat="59.9561501" max_lon="10.7994537" uid="24" user="Petter Reinholdtsen">
+#'     <tag k="created_by" v="JOSM 1.61"/>
+#'     <tag k="comment" v="Just adding some streetnames"/>
+#'     ...
+#'   </changeset>
+#'   <changeset ...>
+#'     ...
+#'   </changeset>
 #' </osm>
 #' ```
 #'
 #' ## `format = "json"`
+#' *Please note that the JSON format has changed on August 25, 2024 with the release of openstreetmap-cgimap 2.0.0, to*
+#' *align it with the existing Rails format.*
+#'
 #' Returns a list with the following json structure:
 #' ``` json
 #' {
-#'  "version": "0.6",
-#'  "elements": [
-#'   {"type": "changeset",
-#'    "id": 10,
-#'    "created_at": "2005-05-01T16:09:37Z",
-#'    "closed_at": "2005-05-01T17:16:44Z",
-#'    "open": False,
-#'    "user": "Petter Reinholdtsen",
-#'    "uid": 24,
-#'    "minlat": 59.9513092,
-#'    "minlon": 10.7719727,
-#'    "maxlat": 59.9561501,
-#'    "maxlon": 10.7994537,
-#'    "comments_count": 1,
-#'    "changes_count": 10,
-#'    "discussion": [{"date": "2022-03-22T20:58:30Z", "uid": 15079200, "user": "Ethan White of Cheriton", "text": "wow no one have said anything here 3/22/2022\n"}]
-#'   }, ...]
+#'   "version": "0.6",
+#'   "generator": "openstreetmap-cgimap 2.0.0 (4003517 spike-08.openstreetmap.org)",
+#'   "copyright": "OpenStreetMap and contributors",
+#'   "attribution": "http://www.openstreetmap.org/copyright",
+#'   "license": "http://opendatacommons.org/licenses/odbl/1-0/",
+#'   "changesets": [
+#'     {
+#'       "id": 10,
+#'       "created_at": "2005-05-01T16:09:37Z",
+#'       "open": false,
+#'       "comments_count": 1,
+#'       "changes_count": 10,
+#'       "closed_at": "2005-05-01T17:16:44Z",
+#'       "min_lat": 59.9513092,
+#'       "min_lon": 10.7719727,
+#'       "max_lat": 59.9561501,
+#'       "max_lon": 10.7994537,
+#'       "uid": 24,
+#'       "user": "Petter Reinholdtsen",
+#'       "tags": {
+#'           "comment": "Just adding some streetnames",
+#'           "created_by": "JOSM 1.61"
+#'       }
+#'     },
+#'     ...
+#'   ]
 #' }
 #' ```
 #'

diff --git a/R/osmapi_changesets.R b/R/osmapi_changesets.R
@@ -238,16 +238,16 @@ osm_create_changeset <- function(comment, ...,
 #' ## `format = "xml"`
 #' Returns a [xml2::xml_document-class] with the following format:
 #' ``` xml
-#' <osm>
+#' <osm version="0.6" generator="CGImap 0.9.3 (987909 spike-08.openstreetmap.org)" copyright="OpenStreetMap and contributors" attribution="http://www.openstreetmap.org/copyright" license="http://opendatacommons.org/licenses/odbl/1-0/">
 #' 	<changeset id="10" created_at="2008-11-08T19:07:39+01:00" open="true" user="fred" uid="123" min_lon="7.0191821" min_lat="49.2785426" max_lon="7.0197485" max_lat="49.2793101" comments_count="3" changes_count="10">
 #' 		<tag k="created_by" v="JOSM 1.61"/>
 #' 		<tag k="comment" v="Just adding some streetnames"/>
 #' 		...
 #' 		<discussion>
-#' 			<comment date="2015-01-01T18:56:48Z" uid="1841" user="metaodi">
+#' 			<comment id="1234" date="2015-01-01T18:56:48Z" uid="1841" user="metaodi">
 #' 				<text>Did you verify those street names?</text>
 #' 			</comment>
-#' 			<comment date="2015-01-01T18:58:03Z" uid="123" user="fred">
+#' 			<comment id="5678" date="2015-01-01T18:58:03Z" uid="123" user="fred">
 #' 				<text>sure!</text>
 #' 			</comment>
 #' 			...
@@ -257,26 +257,41 @@ osm_create_changeset <- function(comment, ...,
 #' ```
 #'
 #' ## `format = "json"`
+#' *Please note that the JSON format has changed on August 25, 2024 with the release of openstreetmap-cgimap 2.0.0, to*
+#' *align it with the existing Rails format.*
+#'
 #' Returns a list with the following json structure:
 #' ``` json
 #' {
-#'  "version": "0.6",
-#'  "elements": [
-#'   {"type": "changeset",
-#'    "id": 10,
-#'    "created_at": "2005-05-01T16:09:37Z",
-#'    "closed_at": "2005-05-01T17:16:44Z",
-#'    "open": False,
-#'    "user": "Petter Reinholdtsen",
-#'    "uid": 24,
-#'    "minlat": 59.9513092,
-#'    "minlon": 10.7719727,
-#'    "maxlat": 59.9561501,
-#'    "maxlon": 10.7994537,
-#'    "comments_count": 1,
-#'    "changes_count": 10,
-#'    "discussion": [{"date": "2022-03-22T20:58:30Z", "uid": 15079200, "user": "Ethan White of Cheriton", "text": "wow no one have said anything here 3/22/2022\n"}]
-#'   }]
+#'   "version": "0.6",
+#'   "generator": "openstreetmap-cgimap 2.0.0 (4003517 spike-08.openstreetmap.org)",
+#'   "copyright": "OpenStreetMap and contributors",
+#'   "attribution": "http://www.openstreetmap.org/copyright",
+#'   "license": "http://opendatacommons.org/licenses/odbl/1-0/",
+#'   "changeset": {
+#'     "id": 10,
+#'     "created_at": "2005-05-01T16:09:37Z",
+#'     "open": false,
+#'     "comments_count": 1,
+#'     "changes_count": 10,
+#'     "closed_at": "2005-05-01T17:16:44Z",
+#'     "min_lat": 59.9513092,
+#'     "min_lon": 10.7719727,
+#'     "max_lat": 59.9561501,
+#'     "max_lon": 10.7994537,
+#'     "uid": 24,
+#'     "user": "Petter Reinholdtsen",
+#'     "comments": [
+#'       {
+#'         "id": 836447,
+#'         "visible": true,
+#'         "date": "2022-03-22T20:58:30Z",
+#'         "uid": 15079200,
+#'         "user": "Ethan White of Cheriton",
+#'         "text": "wow no one have said anything here 3/22/2022\n"
+#'       }
+#'     ]
+#'   }
 #' }
 #' ```
 #'
@@ -538,7 +553,7 @@ osm_download_changeset <- function(changeset_id, format = c("R", "osc", "xml"))
 
 #' Query changesets
 #'
-#' This is an API method for querying changesets. It supports querying by different criteria.
+#' This is an API method for getting a list of changesets. It supports filtering by different criteria.
 #'
 #' @param bbox Find changesets within the given bounding box coordinates (`left,bottom,right,top`).
 #' @param user Find changesets by the user with the given user id (numeric) or display name (character).
@@ -565,8 +580,8 @@ osm_download_changeset <- function(changeset_id, format = c("R", "osc", "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 latest changesets matching criteria. The default ordering is newest first, but you can specify
-#' `order="oldest"` to reverse the sort order (see
+#' This call returns changesets matching criteria, ordered by their creation time. The default ordering is newest first,
+#' but you can specify `order="oldest"` to reverse the sort order (see
 #' [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)).
 #' Reverse ordering cannot be combined with `time`.
@@ -580,48 +595,48 @@ osm_download_changeset <- function(changeset_id, format = c("R", "osc", "xml"))
 #' ## `format = "xml"`
 #' Returns a [xml2::xml_document-class] with the following format:
 #' ``` xml
-#' <osm>
-#' 	<changeset id="10" created_at="2008-11-08T19:07:39+01:00" open="true" user="fred" uid="123" min_lon="7.0191821" min_lat="49.2785426" max_lon="7.0197485" max_lat="49.2793101" comments_count="3" changes_count="10">
-#' 		<tag k="created_by" v="JOSM 1.61"/>
-#' 		<tag k="comment" v="Just adding some streetnames"/>
-#' 		...
-#' 		<discussion>
-#' 			<comment date="2015-01-01T18:56:48Z" uid="1841" user="metaodi">
-#' 				<text>Did you verify those street names?</text>
-#' 			</comment>
-#' 			<comment date="2015-01-01T18:58:03Z" uid="123" user="fred">
-#' 				<text>sure!</text>
-#' 			</comment>
-#' 			...
-#' 		</discussion>
-#' 	</changeset>
-#' 	<changeset ...>
-#' 	  ...
-#' 	</changeset>
+#' <osm version="0.6" generator="OpenStreetMap server" copyright="OpenStreetMap and contributors" attribution="http://www.openstreetmap.org/copyright" license="http://opendatacommons.org/licenses/odbl/1-0/">
+#'   <changeset id="10" created_at="2005-05-01T16:09:37Z" open="false" comments_count="1" changes_count="10" closed_at="2005-05-01T17:16:44Z" min_lat="59.9513092" min_lon="10.7719727" max_lat="59.9561501" max_lon="10.7994537" uid="24" user="Petter Reinholdtsen">
+#'     <tag k="created_by" v="JOSM 1.61"/>
+#'     <tag k="comment" v="Just adding some streetnames"/>
+#'     ...
+#'   </changeset>
+#'   <changeset ...>
+#'     ...
+#'   </changeset>
 #' </osm>
 #' ```
 #'
 #' ## `format = "json"`
 #' Returns a list with the following json structure:
 #' ``` json
 #' {
-#'  "version": "0.6",
-#'  "elements": [
-#'   {"type": "changeset",
-#'    "id": 10,
-#'    "created_at": "2005-05-01T16:09:37Z",
-#'    "closed_at": "2005-05-01T17:16:44Z",
-#'    "open": False,
-#'    "user": "Petter Reinholdtsen",
-#'    "uid": 24,
-#'    "minlat": 59.9513092,
-#'    "minlon": 10.7719727,
-#'    "maxlat": 59.9561501,
-#'    "maxlon": 10.7994537,
-#'    "comments_count": 1,
-#'    "changes_count": 10,
-#'    "discussion": [{"date": "2022-03-22T20:58:30Z", "uid": 15079200, "user": "Ethan White of Cheriton", "text": "wow no one have said anything here 3/22/2022\n"}]
-#'   }, ...]
+#'   "version": "0.6",
+#'   "generator": "openstreetmap-cgimap 2.0.0 (4003517 spike-08.openstreetmap.org)",
+#'   "copyright": "OpenStreetMap and contributors",
+#'   "attribution": "http://www.openstreetmap.org/copyright",
+#'   "license": "http://opendatacommons.org/licenses/odbl/1-0/",
+#'   "changesets": [
+#'     {
+#'       "id": 10,
+#'       "created_at": "2005-05-01T16:09:37Z",
+#'       "open": false,
+#'       "comments_count": 1,
+#'       "changes_count": 10,
+#'       "closed_at": "2005-05-01T17:16:44Z",
+#'       "min_lat": 59.9513092,
+#'       "min_lon": 10.7719727,
+#'       "max_lat": 59.9561501,
+#'       "max_lon": 10.7994537,
+#'       "uid": 24,
+#'       "user": "Petter Reinholdtsen",
+#'       "tags": {
+#'           "comment": "Just adding some streetnames",
+#'           "created_by": "JOSM 1.61"
+#'       }
+#'     },
+#'     ...
+#'   ]
 #' }
 #' ```
 #'