diff --git a/R/changesets.R b/R/changesets.R index f99d7ee3..e85f9271 100644 --- a/R/changesets.R +++ b/R/changesets.R @@ -145,7 +145,7 @@ osm_create_changeset <- function(comment, ..., # GET /api/0.6/changeset/#id?include_discussion=true # # -# +# # # # ... @@ -182,7 +182,7 @@ osm_create_changeset <- function(comment, ..., # "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"}] +# "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"}] # }] # } # @@ -440,7 +440,7 @@ 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 ordered by created_athttps://github.com/openstreetmap/openstreetmap-website/blob/f1c6a87aa137c11d0aff5a4b0e563ac2c2a8f82d/app/controllers/api/changesets_controller.rb#L174 - see the current state at https://github.com/openstreetmap/openstreetmap-website/blob/master/app/controllers/api/changesets_controller.rb#L174. +# This call returns latest changesets matching criteria, ordered by created_athttps://github.com/openstreetmap/openstreetmap-website/blob/f1c6a87aa137c11d0aff5a4b0e563ac2c2a8f82d/app/controllers/api/changesets_controller.rb#L174 - see the current state at https://github.com/openstreetmap/openstreetmap-website/blob/master/app/controllers/api/changesets_controller.rb#L174. # ### Parameters ---- # ; bbox=min_lon,min_lat,max_lon,max_lat (W,S,E,N) @@ -458,9 +458,9 @@ osm_download_changeset <- function(changeset_id, format = c("R", "xml")) { # ; changesets=#cid{,#cid} # : Finds changesets with the specified ids (since [https://github.com/openstreetmap/openstreetmap-website/commit/1d1f194d598e54a5d6fb4f38fb569d4138af0dc8 2013-12-05]) # ; limit=N -# : Specifies the maximum number of changesets returned. A number between 1 and 100, with 100 as the default value. +# : Specifies the maximum number of changesets returned. A number between 1 and the maximum limit value (currently 100). If omitted, the default limit value is used (currently 100). The actual maximum and default limit values can be found with [[API_v0.6#Capabilities:_GET_/api/capabilities| a capabilities request]]. # Time format: -# Anything that [https://ruby-doc.org/3.2.2/exts/date/DateTime.html#method-c-parse this Ruby function] will parse. The default str is ’-4712-01-01T00:00:00+00:00’; this is Julian Day Number day 0. +# Anything that [https://ruby-doc.org/stdlib-2.7.0/libdoc/time/rdoc/Time.html#method-c-parse Time.parse Ruby function] will parse. # ### Response ---- # Returns a list of all changeset ordered by creation date. The `` element may be empty if there were no results for the query. The response is sent with a content type of `text/xml`. @@ -659,7 +659,7 @@ osm_query_changesets <- function(bbox, user, time, time_2, open, closed, changes # | colspan=3| same as uploaded element. # |- # ! new_id -# | new ID || same as uploaded || not present +# | new ID ||new ID ''or'' same as uploaded||not present # |- # ! new_version # | colspan=2| new version || not present @@ -680,6 +680,8 @@ osm_query_changesets <- function(bbox, user, time, time_2, open, closed, changes # : Or if the user trying to update the changeset is not the same as the one that created it # : Or if the diff contains elements with changeset IDs which don't match the changeset ID that the diff was uploaded to # : Or any of the error messages that could occur as a result of a create, update or delete operation for one of the elements +# ; HTTP status code 429 (Too many requests) +# : When the request has been blocked due to rate limiting # ; Other status codes # : Any of the error codes and associated messages that could occur as a result of a create, update or delete operation for one of the elements # : See the according sections in this page diff --git a/R/elements.R b/R/elements.R index 399b3170..4533f04b 100644 --- a/R/elements.R +++ b/R/elements.R @@ -56,6 +56,8 @@ # ; HTTP status code 412 (Precondition Failed) # : When a way has nodes that do not exist or are not visible (i.e. deleted): "`Way #{id} requires the nodes with id in (#{missing_ids}), which either do not exist, or are not visible.`" # : When a relation has elements that do not exist or are not visible: "`Relation with id #{id} cannot be saved due to #{element} with id #{element.id}`" +# ; HTTP status code 429 (Too many requests) +# : When the request has been blocked due to rate limiting # ### Notes ---- # * This updates the bounding box of the changeset. @@ -270,6 +272,8 @@ osm_read_object <- function(osm_type = c("node", "way", "relation"), # ; HTTP status code 412 (Precondition Failed) # : When a way has nodes that do not exist or are not visible (i.e. deleted): "`Way #{id} requires the nodes with id in (#{missing_ids}), which either do not exist, or are not visible.`" # : When a relation has elements that do not exist or are not visible: "`Relation with id #{id} cannot be saved due to #{element} with id #{element.id}`" +# ; HTTP status code 429 (Too many requests) +# : When the request has been blocked due to rate limiting # ### Notes ---- # * This updates the bounding box of the changeset. @@ -403,6 +407,8 @@ osm_update_object <- function(x, changeset_id) { # : When a relation is still member of another relation: `The relation #{id} is used in relation #{relation.id}.` # : # : Note when returned as a result of a OsmChange upload operation the error messages contain a spurious plural "s" as in "... still used by ways ...", "... still used by relations ..." even when only 1 way or relation id is returned, as this implies multiple ids can be returned if the deleted object was/is a member of multiple parent objects, these ids are seperated by commas. +# ; HTTP status code 429 (Too many requests) +# : When the request has been blocked due to rate limiting # ### Notes ---- # * In earlier API versions no payload was required. It is needed now because of the need for changeset IDs and version numbers. diff --git a/R/gps_traces.R b/R/gps_traces.R index 612a2966..37896252 100644 --- a/R/gps_traces.R +++ b/R/gps_traces.R @@ -237,19 +237,22 @@ osm_delete_gpx <- function(gpx_id) { ## Download Metadata: `GET /api/0.6/gpx/#id/details` ---- +# Also available at `GET /api/0.6/gpx/#id` +# # 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. ## TODO: HTTP 401 Unauthorized. (even for public or identificable tracks). FIX wiki or BUG to API ---- # Example "details" response: # # # -# +# # PHP upload test # test # php # # # +# Note: the uid attribute was added in {{gitHub link|openstreetmap/openstreetmap-website/pull/4241| September 2023}}. #' Download GPS Track Metadata #' @@ -364,15 +367,20 @@ osm_get_data_gpx <- function(gpx_id, format) { # # Note that '''/user/''' is a literal part of the URL, not a user's display name or user id. (This call always returns GPX traces for the current authenticated user ''only''.) # -# Example "details" response: +# The response is similar to the one of [[API_v0.6#Download_Metadata:_GET_/api/0.6/gpx/#id/details| Download Metadata]], except with multiple possible `` elements. Example: # # # -# +# # PHP upload test # test # php # +# +# PHP upload test 2 +# test +# php +# # # diff --git a/R/map_notes.R b/R/map_notes.R index bd1fea83..3c3d1161 100644 --- a/R/map_notes.R +++ b/R/map_notes.R @@ -23,12 +23,12 @@ # |- # | bbox # | Coordinates for the area to retrieve the notes from -# | Floating point numbers in degrees, expressing a valid bounding box, not larger than the configured size limit, 25 square degrees [https://github.com/openstreetmap/openstreetmap-website/blob/master/config/settings.yml#L27], not overlapping the dateline. +# | Floating point numbers in degrees, expressing a valid bounding box, not larger than the configured size limit, 25 square degrees{{efn| see [[API_v0.6#Capabilities:_GET_/api/capabilities| capabilities]] and [https://github.com/openstreetmap/openstreetmap-website/blob/master/config/settings.yml#L27 this line in settings] for the current value}}, not overlapping the dateline. # | none, parameter required # |- # | limit # | Specifies the number of entries returned at max -# | A value of between 1 and 10000 is valid +# | A value of between 1 and 10000 {{efn|name=limit| may change, see [[API_v0.6#Capabilities:_GET_/api/capabilities| capabilities]] for current value}} is valid # | 100 is the default # |- # | closed @@ -157,12 +157,12 @@ osm_read_bbox_notes <- function(bbox, limit = 100, closed = 7, format = c("R", " # # Returns the existing note with the given ID. The output can be in several formats (e.g. XML, RSS, json or GPX) depending on the file extension. # -# '''URL:''' https://api.openstreetmap.org/api/0.6/notes/#id ([https://api.openstreetmap.org/api/0.6/notes/100])
+# '''URL:''' https://api.openstreetmap.org/api/0.6/notes/#id ([https://api.openstreetmap.org/api/0.6/notes/100 xml], [https://api.openstreetmap.org/api/0.6/notes/100.json json])
# '''Return type:''' application/xml
# ### Error codes ---- # ; HTTP status code 404 (Not Found) -# : When no note with the given id could be found +# : When no note with the given id could be found. Currently both deleted and not yet existing notes give 404 error. #' Read notes #' @@ -251,7 +251,7 @@ osm_read_note <- function(note_id, format = c("R", "xml", "rss", "json", "gpx")) # | No default, needs to be present # |} # -# 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. # ### Error codes ---- # ; HTTP status code 400 (Bad Request) @@ -490,11 +490,11 @@ osm_delete_note <- function(note_id) { ## Search for notes: `GET /api/0.6/notes/search` ---- # -# Returns the existing notes matching either the initial note text or any of the comments. 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 list of notes can be returned in several different forms (e.g. XML, RSS, json or GPX) depending on file extension given. +# Returns notes that match the specified query. If no query is provided, the most recently updated notes are returned. # -# '''URL:''' https://api.openstreetmap.org/api/0.6/notes/search?q=SearchTerm -# ([https://api.openstreetmap.org/api/0.6/notes/search?q=Spam example])
-# '''Return type:''' application/xml
+# The result can be encoded in several different formats (XML, RSS, JSON, or GPX), depending on the file extension provided. +# +# '''URL:''' https://api.openstreetmap.org/api/0.6/notes/search # # {| class="wikitable" # |- @@ -504,51 +504,66 @@ osm_delete_note <- function(note_id) { # ! Default value # |- # | q -# | Specifies the search query +# | Text search query, matching either note text or comments. # | String -# | none, parameter required +# | none, optional parameter # |- # | limit -# | Specifies the number of entries returned at max -# | A value of between 1 and 10000 is valid -# | 100 is the default +# | Maximum number of results. +# | Integer between 1 and 10000{{efn|name=limit| may change, see [[API_v0.6#Capabilities:_GET_/api/capabilities| capabilities]] for the current value}} +# | 100{{efn|name=limit}} # |- # | 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 +# | Maximum number of days a note has been closed for. +# | Number; Value of 0 returns only open notes, Negative numbers return all notes +# | 7 # |- # |display_name -# |Specifies the person involved in actions of the returned notes, query by the display name. Does not work together with the user parameter (Returned are all where this user has taken some action - opened note, commented on, reactivated, or closed) -# |A valid user name -# |none, optional parameter +# | Search for notes which the given user interacted with. +# | String; User display name +# | none, optional parameter # |- # |user -# |Specifies the creator of the returned notes by the id of the user. Does not work together with the display_name parameter -# |A valid user id -# |none, optional parameter +# | 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 +# |- +# |bbox +# | Search area. +# | [[API_v0.6#Retrieving_notes_data_by_bounding_box:_GET_/api/0.6/notes|Bounding box]]; Area of at most 25 square degrees{{efn| see [[API_v0.6#Capabilities:_GET_/api/capabilities| capabilities]] and [https://github.com/openstreetmap/openstreetmap-website/blob/master/config/settings.yml#L27 this line in settings] for the current value}} +# | none, optional parameter # |- # |from -# |Specifies the beginning of a date range to search in for a note -# |A valid [https://en.wikipedia.org/wiki/ISO_8601 ISO 8601] date -# |none, optional parameter +# | Beginning date range for created_at or updated_at (specified by sort). +# | Date; Preferably in [https://wikipedia.org/wiki/ISO_8601 ISO 8601] format +# | none, optional parameter # |- # |to -# |Specifies the end of a date range to search in for a note -# |A valid [https://en.wikipedia.org/wiki/ISO_8601 ISO 8601] date -# |the date of today is the default, optional parameter +# | End date range for created_at or updated_at (specified by sort). Only works when from is supplied. +# | Date; Preferably in [https://wikipedia.org/wiki/ISO_8601 ISO 8601] format +# | none, optional parameter # |- # |sort -# |Specifies the value which should be used to sort the notes. It is either possible to sort them by their creation date or the date of the last update. -# |created_at or updated_at -# |updated_at +# | Sort results by creation or update date. +# | created_at or updated_at +# | updated_at # |- # |order -# |Specifies the order of the returned notes. It is possible to order them in ascending or descending order. -# |oldest or newest -# |newest +# | Sorting order. oldest is ascending order, newest is descending order. +# | oldest or newest +# | newest # |} # +### Examples ---- +# See latest note updates globally: +# https://api.openstreetmap.org/api/0.6/notes/search +# Search for a text in comments: +# https://api.openstreetmap.org/api/0.6/notes/search?q=business%20spam +# See notes of a single user: +# https://api.openstreetmap.org/api/0.6/notes/search?user=123 +# Search for oldest notes near Null Island: +# https://api.openstreetmap.org/api/0.6/notes/search?bbox=-1%2C-1%2C1%2C1&sort=created_at&order=oldest&closed=-1&limit=20 +# ### Error codes ---- # ; HTTP status code 400 (Bad Request) # : When any of the limits are crossed @@ -653,9 +668,22 @@ osm_search_notes <- function( # # Gets an RSS feed for notes within an area. # -# '''URL:''' https://api.openstreetmap.org/api/0.6/notes/feed?bbox=''left'',''bottom'',''right'',''top'' +# '''URL:''' https://api.openstreetmap.org/api/0.6/notes/feed # # '''Return type:''' application/xml +# +# {| class="wikitable" +# |- +# ! Parameter +# ! Description +# ! Allowed values +# ! Default value +# |- +# |bbox +# | Coordinates for the area to retrieve the notes from +# | Floating point numbers in degrees, expressing a valid bounding box, not larger than the configured size limit, 25 square degrees [https://github.com/openstreetmap/openstreetmap-website/blob/master/config/settings.yml#L27], not overlapping the dateline. +# | none, optional parameter +# |} #' RSS Feed of notes in a bbox #' diff --git a/R/miscellaneous.R b/R/miscellaneous.R index d6bcc429..25a65228 100644 --- a/R/miscellaneous.R +++ b/R/miscellaneous.R @@ -5,6 +5,9 @@ # # Returns a list of API versions supported by this instance. # +### Response XML ---- +# `GET /api/versions` +# # # # @@ -13,6 +16,19 @@ # # # +# +### Response JSON ---- +# `GET /api/versions.json``` +# +# +# { +# "version": "0.6", +# "generator": "OpenStreetMap server", +# "api": { +# "versions": ["0.6"] +# } +# } +# #' Available API versions #' @@ -54,6 +70,7 @@ osm_api_versions <- function() { # # # +# # # # @@ -78,6 +95,7 @@ osm_api_versions <- function() { # * '''relationmembers''' '''maximum''' is the maximum number of members that a relation may contain. (''added in February 2022'') # * '''changesets''' '''maximum_elements''' is the maximum number of combined nodes, ways and relations that can be contained in a changeset. # * '''changesets''' '''default_query_limit''' and '''maximum_query_limit''' are the default and maximum values of the limit parameter of [[API v0.6#Query:_GET_/api/0.6/changesets|changeset queries]]. (''added in {{GitHub link|openstreetmap/openstreetmap-website/pull/4142| August 2023}}'') +# * '''notes''' '''default_query_limit''' and '''maximum_query_limit''' are the default and maximum values of the limit parameter of notes [[API_v0.6#Retrieving_notes_data_by_bounding_box:_GET_/api/0.6/notes| bounding box queries]] and [[API_v0.6#Search_for_notes:_GET_/api/0.6/notes/search| search]]. (''added in {{GitHub link|openstreetmap/openstreetmap-website/pull/4187| August 2023}}'') # * 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''' 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'').# # # Policy: diff --git a/R/user_data.R b/R/user_data.R index 874b894e..e9dbc1c2 100644 --- a/R/user_data.R +++ b/R/user_data.R @@ -132,6 +132,7 @@ osm_details_user <- function(user_id, format = c("R", "xml", "json")) { # # # or an empty file if no user found for given identifier. +# Note: Since [https://github.com/openstreetmap/openstreetmap-website/pull/4203 Pull request 4203 (deployed on August 26 2023)], both XML and JSON based variants of the users endpoint will skip any non-existing/suspended/deleted users, rather than reporting a previously undocumented HTTP 404 error. #' Details of multiple users #'