Merge pull request #69 from ropensci/update_wiki

jmaspons · web-flow · commit 1e28e8c22339 · 2025-07-30T20:53:55.000+02:00
Update API wiki version
diff --git a/DESCRIPTION b/DESCRIPTION
@@ -1,7 +1,7 @@
 Type: Package
 Package: osmapiR
 Title: 'OpenStreetMap' API
-Version: 0.2.3.9001
+Version: 0.2.3.9002
 Authors@R: c(
     person("Joan", "Maspons", , "joanmaspons@gmail.com", role = c("aut", "cre", "cph"),
            comment = c(ORCID = "0000-0003-2286-8727")),
diff --git a/NEWS.md b/NEWS.md
@@ -1,6 +1,10 @@
 # osmapiR (development version)
 
 * Fix for upcoming httr2 1.2.0 release (#67 by @hadley).
+* Update documentation and code for server-side changes documented in OSMWikiVersion
+  [2834473 -> 2878437](https://wiki.openstreetmap.org/w/index.php?title=API_v0.6&diff=2878437&oldid=2834473) (#69).
+  * Add `format = "json"` for `osm_get_gpx_metadata()`.
+  * New default for `osm_search_notes()` to `sort = "created_at"` instead of `sort = "updated_at"`.
 
 # osmapiR 0.2.3
 
diff --git a/OSMwiki_version b/OSMwiki_version
@@ -1,2 +1,2 @@
-# last synchronized version of https://wiki.openstreetmap.org/wiki/API_v0.6. Diff current https://wiki.openstreetmap.org/w/index.php?title=API_v0.6&diff=cur&oldid=2834473
-2834473
+# last synchronized version of https://wiki.openstreetmap.org/wiki/API_v0.6. Diff current https://wiki.openstreetmap.org/w/index.php?title=API_v0.6&diff=cur&oldid=2878437
+2878437
diff --git a/R/osm_get_gpx_metadata.R b/R/osm_get_gpx_metadata.R
@@ -6,7 +6,7 @@
 #' Otherwise only usable by the owner account and requires authentication.
 #'
 #' @param gpx_id A vector of track ids represented by a numeric or a character value.
-#' @param format Format of the output. Can be `"R"` (default), `"sf"`, or `"xml"`.
+#' @param format Format of the output. Can be `"R"` (default), `"sf"`, `"xml"`, or `"json"`.
 #'
 #' @return
 #' If `format = "R"`, returns a data frame with one trace per row. If `format = "sf"`, returns a `sf` object from
@@ -24,6 +24,7 @@
 #'   </gpx_file>
 #' </osm>
 #' ```
+#' If `format = "json"`, returns a list with the json structure.
 #' @family get GPS' functions
 #' @export
 #'
@@ -32,7 +33,7 @@
 #' trk_meta <- osm_get_gpx_metadata(gpx_id = 3498170)
 #' trk_meta
 #' }
-osm_get_gpx_metadata <- function(gpx_id, format = c("R", "sf", "xml")) {
+osm_get_gpx_metadata <- function(gpx_id, format = c("R", "sf", "xml", "json")) {
   format <- match.arg(format)
   .format <- if (format == "sf") "R" else format
   if (format == "sf" && !requireNamespace("sf", quietly = TRUE)) {
@@ -55,6 +56,10 @@ osm_get_gpx_metadata <- function(gpx_id, format = c("R", "sf", "xml")) {
           xml2::xml_add_child(out, node)
         })
       }
+    } else if (.format == "json") {
+      out <- outL[[1]]
+      out$traces <- lapply(outL, function(x) x$trace)
+      out$trace <- NULL
     }
   }
 
diff --git a/R/osmapi_elements.R b/R/osmapi_elements.R
@@ -685,7 +685,7 @@ osm_version_object <- function(osm_type = c("node", "way", "relation"), osm_id,
 # ; HTTP status code 400 (Bad Request)
 # : On a malformed request (parameters missing or wrong)
 # ; HTTP status code 404 (Not Found)
-# : If one of the elements could not be found (By "not found" is meant never existed in the database, if the object was deleted, it will be returned with the attribute visible="false")
+# : If one of the elements could not be found (By "not found" is meant never existed in the database  or its requested version was redacted, if the object was deleted, it will be returned with the attribute visible="false")
 # ; HTTP status code 414 (Request-URI Too Large)
 # : If the URI was too long (tested to be > 8213 characters in the URI, or > 725 elements for 10 digit IDs when not specifying versions)
 #
diff --git a/R/osmapi_gps_traces.R b/R/osmapi_gps_traces.R
@@ -133,7 +133,7 @@
 # |The GPX file containing the track points. Note that for successful processing, the file must contain trackpoints (<code><trkpt></code>), not only waypoints, and the trackpoints must have a valid timestamp. Since the file is processed asynchronously, the call will complete successfully even if the file cannot be processed. The file may also be a .tar, .tar.gz or .zip containing multiple gpx files, although it will appear as a single entry in the upload log.
 # |-
 # |description
-# |The trace description. Cannot be empty.
+# |The trace description. Cannot be empty. Maximum length is 255 characters.
 # |-
 # |tags
 # |A string containing tags for the trace. Can be empty.
@@ -156,7 +156,7 @@
 #' Use this to upload a GPX file or archive of GPX files. Requires authentication.
 #'
 #' @param file The GPX file path containing the track points.
-#' @param description The trace description. Cannot be empty.
+#' @param description The trace description. Cannot be empty. Maximum length is 255 characters.
 #' @param tags A string containing tags for the trace. Can be empty.
 #' @param visibility One of the following: `private`, `public`, `trackable`, `identifiable`. For explanations see
 #'   [OSM trace upload page](https://www.openstreetmap.org/traces/mine) or
@@ -311,14 +311,16 @@ osm_update_gpx <- function(gpx_id, name, description, tags,
 # </osm>
 # </syntaxhighlight>
 # Note: the <code>uid</code> attribute was added in {{gitHub link|openstreetmap/openstreetmap-website/pull/4241| September 2023}}.
+#
+# This API call also supports a JSON response.
 
 #' Download GPS Track Metadata
 #'
 #' Use this to access the metadata about a GPX file. Available without authentication if the file is marked public.
 #' Otherwise only usable by the owner account and requires authentication.
 #'
 #' @param gpx_id The track id represented by a numeric or a character value.
-#' @param format Format of the output. Can be `"R"` (default) or `"xml"`.
+#' @param format Format of the output. Can be `"R"` (default), `"xml"`, or `"json"`.
 #'
 #' @return
 #' If `format = "R"`, returns a data frame with one trace per row. If `format = "xml"`, returns a
@@ -341,19 +343,26 @@ osm_update_gpx <- function(gpx_id, name, description, tags,
 #' trk_meta <- osm_get_metadata_gpx(gpx_id = 3498170)
 #' trk_meta
 #' }
-osm_get_metadata_gpx <- function(gpx_id, format = c("R", "xml")) {
+osm_get_metadata_gpx <- function(gpx_id, format = c("R", "xml", "json")) {
   format <- match.arg(format)
+
+  if (format == "json") {
+    gpx_id <- paste0(gpx_id, ".json")
+  }
+
   req <- osmapi_request(authenticate = TRUE)
   req <- httr2::req_method(req, "GET")
   req <- httr2::req_url_path_append(req, "gpx", gpx_id)
 
   resp <- httr2::req_perform(req)
-  obj_xml <- httr2::resp_body_xml(resp)
 
-  if (format == "R") {
-    out <- gpx_meta_xml2DF(obj_xml)
-  } else {
-    out <- obj_xml
+  if (format %in% c("R", "xml")) {
+    out <- httr2::resp_body_xml(resp)
+    if (format == "R") {
+      out <- gpx_meta_xml2DF(out)
+    }
+  } else if (format %in% "json") {
+    out <- httr2::resp_body_json(resp)
   }
 
   return(out)
diff --git a/R/osmapi_map_notes.R b/R/osmapi_map_notes.R
@@ -715,7 +715,7 @@ osm_unsubscribe_note <- function(note_id) { # TODO: , format = c("R", "xml", "js
 # |<code>sort</code>
 # | Sort results by creation or update date.
 # | <code>created_at</code> or <code>updated_at</code>
-# | <code>updated_at</code>
+# | <code>created_at</code>
 # |-
 # |<code>order</code>
 # | Sorting order. <code>oldest</code> is ascending order, <code>newest</code> is descending order.
@@ -755,7 +755,7 @@ osm_unsubscribe_note <- function(note_id) { # TODO: , format = c("R", "xml", "js
 #'   [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 Sort results by creation (`"created_at"`) or update date (`"updated_at"`, the default).
+#' @param sort Sort results by creation (`"created_at"`, the default) or update date (`"updated_at"`).
 #' @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.
@@ -786,7 +786,7 @@ osm_unsubscribe_note <- function(note_id) { # TODO: , format = c("R", "xml", "js
 #' my_notes
 osm_search_notes <- function(
     q, user, bbox, from, to, closed = 7,
-    sort = c("updated_at", "created_at"), order = c("newest", "oldest"),
+    sort = c("created_at", "updated_at"), order = c("newest", "oldest"),
     limit = getOption("osmapir.api_capabilities")$api$notes["default_query_limit"],
     format = c("R", "sf", "xml", "rss", "json", "gpx")) {
   sort <- match.arg(sort)
diff --git a/codemeta.json b/codemeta.json
@@ -8,7 +8,7 @@
   "codeRepository": "https://github.com/ropensci/osmapiR",
   "issueTracker": "https://github.com/ropensci/osmapiR/issues",
   "license": "https://spdx.org/licenses/GPL-3.0",
-  "version": "0.2.3.9001",
+  "version": "0.2.3.9002",
   "programmingLanguage": {
     "@type": "ComputerLanguage",
     "name": "R",
@@ -164,7 +164,7 @@
     "SystemRequirements": null
   },
   "keywords": ["openstreetmap", "OSM", "openstreetmap-api", "osmapi", "API", "osm", "r", "r-package"],
-  "fileSize": "14152.15KB",
+  "fileSize": "14155.039KB",
   "citation": [
     {
       "@type": "ScholarlyArticle",
@@ -180,7 +180,7 @@
       ],
       "name": "osmapiR: An 'OpenStreetMap API' implementation for R",
       "identifier": "10.21105/joss.07151",
-      "description": "R package version 0.2.3.9001",
+      "description": "R package version 0.2.3.9002",
       "pagination": "7151",
       "@id": "https://doi.org/10.21105/joss.07151",
       "sameAs": "https://doi.org/10.21105/joss.07151",
diff --git a/man/osm_create_gpx.Rd b/man/osm_create_gpx.Rd
diff --git a/man/osm_get_gpx_metadata.Rd b/man/osm_get_gpx_metadata.Rd
diff --git a/man/osm_search_notes.Rd b/man/osm_search_notes.Rd
diff --git a/tests/testthat/mock_get_metadata_gpx/osm.org/api/0.6/gpx/3458743.json.json b/tests/testthat/mock_get_metadata_gpx/osm.org/api/0.6/gpx/3458743.json.json
@@ -0,0 +1,23 @@
+{
+    "version": "0.6",
+    "generator": "OpenStreetMap server",
+    "copyright": "OpenStreetMap and contributors",
+    "attribution": "http://www.openstreetmap.org/copyright",
+    "license": "http://opendatacommons.org/licenses/odbl/1-0/",
+    "trace": {
+        "id": 3458743,
+        "name": "not_saved",
+        "uid": 11725140,
+        "user": "jmaspons",
+        "visibility": "identifiable",
+        "pending": false,
+        "timestamp": "2020-10-12T11:08:58Z",
+        "lat": 41.71107572503388,
+        "lon": 2.236165450885892,
+        "description": "Puiggiró",
+        "tags": [
+            "explorant",
+            "Cingles de Bertí"
+        ]
+    }
+}
diff --git a/tests/testthat/mock_get_metadata_gpx/osm.org/api/0.6/gpx/3790367.json.json b/tests/testthat/mock_get_metadata_gpx/osm.org/api/0.6/gpx/3790367.json.json
@@ -0,0 +1,24 @@
+{
+    "version": "0.6",
+    "generator": "OpenStreetMap server",
+    "copyright": "OpenStreetMap and contributors",
+    "attribution": "http://www.openstreetmap.org/copyright",
+    "license": "http://opendatacommons.org/licenses/odbl/1-0/",
+    "trace": {
+        "id": 3790367,
+        "name": "Airoto_Marimanha.gpx",
+        "uid": 11725140,
+        "user": "jmaspons",
+        "visibility": "public",
+        "pending": false,
+        "timestamp": "2021-08-20T10:30:15Z",
+        "lat": 42.69660229794681,
+        "lon": 1.0419843904674053,
+        "description": "Airoto Marimanha Oriental",
+        "tags": [
+            "camp",
+            "a",
+            "través"
+        ]
+    }
+}
diff --git a/tests/testthat/test-gps_traces.R b/tests/testthat/test-gps_traces.R
@@ -206,6 +206,7 @@ test_that("osm_get_metadata_gpx works", {
   trk_meta <- list()
   sf_trk_meta <- list()
   xml_trk_meta <- list()
+  json_trk_meta <- list()
   with_mock_dir("mock_get_metadata_gpx", {
     trk_meta$track <- osm_get_gpx_metadata(gpx_id = 3790367)
     trk_meta$tracks <- osm_get_gpx_metadata(gpx_id = c(3790367, 3458743))
@@ -215,6 +216,9 @@ test_that("osm_get_metadata_gpx works", {
 
     xml_trk_meta$track_xml <- osm_get_gpx_metadata(gpx_id = 3790367, format = "xml")
     xml_trk_meta$tracks_xml <- osm_get_gpx_metadata(gpx_id = c(3790367, 3458743), format = "xml")
+
+    json_trk_meta$track_json <- osm_get_gpx_metadata(gpx_id = 3790367, format = "json")
+    json_trk_meta$tracks_json <- osm_get_gpx_metadata(gpx_id = c(3790367, 3458743), format = "json")
   })
 
   lapply(trk_meta, function(x) expect_s3_class(x, class = "data.frame", exact = TRUE))
@@ -240,15 +244,22 @@ test_that("osm_get_metadata_gpx works", {
 
   lapply(xml_trk_meta, expect_s3_class, class = "xml_document")
 
+  lapply(json_trk_meta, expect_type, type = "list")
+  expect_named(json_trk_meta$track_json, c("version", "generator", "copyright", "attribution", "license", "trace"))
+  expect_named(json_trk_meta$tracks_json, c("version", "generator", "copyright", "attribution", "license", "traces"))
+
+
+  # Compare xml, json & R
 
-  # Compare xml & R
   mapply(function(d, x) {
     expect_identical(nrow(d), xml2::xml_length(x))
   }, d = trk_meta, x = xml_trk_meta)
 
   mapply(function(d, x) {
     expect_identical(nrow(d), nrow(x))
   }, d = trk_meta, x = sf_trk_meta)
+
+  expect_identical(nrow(trk_meta$tracks), length(json_trk_meta$tracks_json$traces))
 })
 
 
diff --git a/tests/testthat/test-map_notes.R b/tests/testthat/test-map_notes.R
@@ -220,14 +220,24 @@ test_that("osm_subscribe_note works", {
 test_that("osm_search_notes works", {
   search_notes <- list()
   with_mock_dir("mock_search_notes", {
-    search_notes$df <- osm_search_notes(q = "POI", from = "2017-10-01", to = "2017-10-27T15:27A", limit = 10)
+    search_notes$df <- osm_search_notes(
+      q = "POI", from = "2017-10-01", to = "2017-10-27T15:27A", sort = "updated_at", limit = 10
+    )
     search_notes$sf <- osm_search_notes(
-      q = "POI", from = "2017-10-01", to = "2017-10-27T15:27A", limit = 10, format = "sf"
+      q = "POI", from = "2017-10-01", to = "2017-10-27T15:27A", sort = "updated_at", limit = 10, format = "sf"
+    )
+    search_notes$xml <- osm_search_notes(
+      user = "jmaspons", from = "2017-10-01", sort = "updated_at", limit = 10, format = "xml"
+    )
+    search_notes$rss <- osm_search_notes(
+      q = "POI", from = "2017-10-01", to = "2017-10-27", sort = "updated_at", limit = 10, format = "rss"
+    )
+    search_notes$json <- osm_search_notes(
+      from = "2017-10-01", to = "2017-10-27", sort = "updated_at", limit = 10, format = "json"
+    )
+    search_notes$gpx <- osm_search_notes(
+      from = "2023-06-25", closed = -1, sort = "updated_at", limit = 10, format = "gpx"
     )
-    search_notes$xml <- osm_search_notes(user = "jmaspons", from = "2017-10-01", limit = 10, format = "xml")
-    search_notes$rss <- osm_search_notes(q = "POI", from = "2017-10-01", to = "2017-10-27", limit = 10, format = "rss")
-    search_notes$json <- osm_search_notes(from = "2017-10-01", to = "2017-10-27", limit = 10, format = "json")
-    search_notes$gpx <- osm_search_notes(from = "2023-06-25", closed = -1, limit = 10, format = "gpx")
   })
 
   mapply(function(x, class) expect_true(inherits(x, class)), x = search_notes, class = classes)
@@ -256,12 +266,22 @@ test_that("osm_search_notes works", {
 
   empty_search_notes <- list()
   with_mock_dir("mock_search_notes_empty", {
-    empty_search_notes$df <- osm_search_notes(q = "Visca la terra!", user = "jmaspons")
-    empty_search_notes$sf <- osm_search_notes(q = "Visca la terra!", user = "jmaspons", format = "sf")
-    empty_search_notes$xml <- osm_search_notes(q = "Visca la terra!", user = "jmaspons", format = "xml")
-    empty_search_notes$rss <- osm_search_notes(q = "Visca la terra!", user = "jmaspons", format = "rss")
-    empty_search_notes$json <- osm_search_notes(q = "Visca la terra!", user = "jmaspons", format = "json")
-    empty_search_notes$gpx <- osm_search_notes(q = "Visca la terra!", user = "jmaspons", format = "gpx")
+    empty_search_notes$df <- osm_search_notes(q = "Visca la terra!", user = "jmaspons", sort = "updated_at")
+    empty_search_notes$sf <- osm_search_notes(
+      q = "Visca la terra!", user = "jmaspons", sort = "updated_at", format = "sf"
+    )
+    empty_search_notes$xml <- osm_search_notes(
+      q = "Visca la terra!", user = "jmaspons", sort = "updated_at", format = "xml"
+    )
+    empty_search_notes$rss <- osm_search_notes(
+      q = "Visca la terra!", user = "jmaspons", sort = "updated_at", format = "rss"
+    )
+    empty_search_notes$json <- osm_search_notes(
+      q = "Visca la terra!", user = "jmaspons", sort = "updated_at", format = "json"
+    )
+    empty_search_notes$gpx <- osm_search_notes(
+      q = "Visca la terra!", user = "jmaspons", sort = "updated_at", format = "gpx"
+    )
   })
 
   mapply(function(x, class) expect_true(inherits(x, class)), x = empty_search_notes, class = classes)

-Original file line number
+Diff line change
@@ @@ -1,2 +1,2 @@ @@
 -# last synchronized version of https://wiki.openstreetmap.org/wiki/API_v0.6. Diff current https://wiki.openstreetmap.org/w/index.php?title=API_v0.6&diff=cur&oldid=2834473
 -2834473
 +# last synchronized version of https://wiki.openstreetmap.org/wiki/API_v0.6. Diff current https://wiki.openstreetmap.org/w/index.php?title=API_v0.6&diff=cur&oldid=2878437
 +2878437
Original file line number	Diff line number	Diff line change
`@@ -685,7 +685,7 @@ osm_version_object <- function(osm_type = c("node", "way", "relation"), osm_id,`
`685`	`685`	`# ; HTTP status code 400 (Bad Request)`
`686`	`686`	`# : On a malformed request (parameters missing or wrong)`
`687`	`687`	`# ; HTTP status code 404 (Not Found)`
`688`		`-# : If one of the elements could not be found (By "not found" is meant never existed in the database, if the object was deleted, it will be returned with the attribute visible="false")`
	`688`	`+# : If one of the elements could not be found (By "not found" is meant never existed in the database or its requested version was redacted, if the object was deleted, it will be returned with the attribute visible="false")`
`689`	`689`	`# ; HTTP status code 414 (Request-URI Too Large)`
`690`	`690`	`# : If the URI was too long (tested to be > 8213 characters in the URI, or > 725 elements for 10 digit IDs when not specifying versions)`
`691`	`691`	`#`