Skip to content

Commit

Permalink
https://wiki.openstreetmap.org/w/index.php?title=API_v0.6&diff=cur&ol…
Browse files Browse the repository at this point in the history 
…did=2585039
  • Loading branch information
@jmaspons
jmaspons committed Dec 14, 2023
1 parent 4ea6346 commit 84d4907
Show file tree
Hide file tree
Showing 6 changed files with 108 additions and 45 deletions.
14 changes: 8 additions & 6 deletions R/changesets.R
View file
Original file line number Diff line number Diff line change
Expand Up @@ -145,7 +145,7 @@ osm_create_changeset <- function(comment, ...,
# GET /api/0.6/changeset/#id?include_discussion=true
# <syntaxhighlight lang="xml">
# <osm>
# <changeset id="10" user="fred" uid="123" created_at="2008-11-08T19:07:39+01:00" open="true" min_lon="7.0191821" min_lat="49.2785426" max_lon="7.0197485" max_lat="49.2793101">
# <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"/>
# ...
Expand Down Expand Up @@ -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"}]
# }]
# }
# </syntaxhighlight>
Expand Down Expand Up @@ -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_at<ref>https://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</ref>.
# This call returns latest changesets matching criteria, ordered by created_at<ref>https://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</ref>.
#
### Parameters ----
# ; bbox=min_lon,min_lat,max_lon,max_lat (W,S,E,N)
Expand All @@ -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 <code>Time.parse</code> Ruby function] will parse.
#
### Response ----
# Returns a list of all changeset ordered by creation date. The `<osm>` element may be empty if there were no results for the query. The response is sent with a content type of `text/xml`.
Expand Down Expand Up @@ -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
Expand All @@ -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
Expand Down
6 changes: 6 additions & 0 deletions R/elements.R
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down Expand Up @@ -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.
Expand Down Expand Up @@ -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.
Expand Down
14 changes: 11 additions & 3 deletions R/gps_traces.R
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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:
# <syntaxhighlight lang="xml">
# <?xml version="1.0" encoding="UTF-8"?>
# <osm version="0.6" generator="OpenStreetMap server">
# <gpx_file id="836619" name="track.gpx" lat="52.0194" lon="8.51807" user="Hartmut Holzgraefe" visibility="public" pending="false" timestamp="2010-10-09T09:24:19Z">
# <gpx_file id="836619" name="track.gpx" lat="52.0194" lon="8.51807" uid="1234" user="Hartmut Holzgraefe" visibility="public" pending="false" timestamp="2010-10-09T09:24:19Z">
# <description>PHP upload test</description>
# <tag>test</tag>
# <tag>php</tag>
# </gpx_file>
# </osm>
# </syntaxhighlight>
# Note: the <code>uid</code> attribute was added in {{gitHub link|openstreetmap/openstreetmap-website/pull/4241| September 2023}}.

#' Download GPS Track Metadata
#'
Expand Down Expand Up @@ -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 `<gpx_file>` elements. Example:
# <syntaxhighlight lang="xml">
# <?xml version="1.0" encoding="UTF-8"?>
# <osm version="0.6" generator="OpenStreetMap server">
# <gpx_file id="836619" name="track.gpx" lat="52.0194" lon="8.51807" user="Hartmut Holzgraefe" visibility="public" pending="false" timestamp="2010-10-09T09:24:19Z">
# <gpx_file id="836619" name="track.gpx" lat="52.0194" lon="8.51807" uid="1234" user="Hartmut Holzgraefe" visibility="public" pending="false" timestamp="2010-10-09T09:24:19Z">
# <description>PHP upload test</description>
# <tag>test</tag>
# <tag>php</tag>
# </gpx_file>
# <gpx_file id="836620" name="track.gpx" lat="52.1194" lon="8.61807" uid="1234" user="Hartmut Holzgraefe" visibility="public" pending="false" timestamp="2010-10-09T09:27:31Z">
# <description>PHP upload test 2</description>
# <tag>test</tag>
# <tag>php</tag>
# </gpx_file>
# </osm>
# </syntaxhighlight>

Expand Down
100 changes: 64 additions & 36 deletions R/map_notes.R
View file
Original file line number Diff line number Diff line change
Expand Up @@ -23,12 +23,12 @@
# |-
# | <code>bbox</code>
# | 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
# |-
# | <code>limit</code>
# | 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
# |-
# | <code>closed</code>
Expand Down Expand Up @@ -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:''' <code>https://api.openstreetmap.org/api/0.6/notes/#id</code> ([https://api.openstreetmap.org/api/0.6/notes/100])<br />
# '''URL:''' <code>https://api.openstreetmap.org/api/0.6/notes/#id</code> ([https://api.openstreetmap.org/api/0.6/notes/100 xml], [https://api.openstreetmap.org/api/0.6/notes/100.json json])<br />
# '''Return type:''' application/xml <br />
#
### 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
#'
Expand Down Expand Up @@ -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)
Expand Down Expand Up @@ -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:''' <code>https://api.openstreetmap.org/api/0.6/notes/search?q=SearchTerm
# </code> ([https://api.openstreetmap.org/api/0.6/notes/search?q=Spam example])<br />
# '''Return type:''' application/xml<br />
# The result can be encoded in several different formats (XML, RSS, JSON, or GPX), depending on the file extension provided.
#
# '''URL:''' <code><nowiki>https://api.openstreetmap.org/api/0.6/notes/search
#
# {| class="wikitable"
# |-
Expand All @@ -504,51 +504,66 @@ osm_delete_note <- function(note_id) {
# ! Default value
# |-
# | <code>q</code>
# | Specifies the search query
# | Text search query, matching either note text or comments.
# | String
# | none, parameter required
# | none, optional parameter
# |-
# | <code>limit</code>
# | 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}}
# |-
# | <code>closed</code>
# | 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
# |-
# |<code>display_name</code>
# |Specifies the person involved in actions of the returned notes, query by the display name. Does not work together with the <code>user</code> 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
# |-
# |<code>user</code>
# |Specifies the creator of the returned notes by the id of the user. Does not work together with the <code>display_name</code> parameter
# |A valid user id
# |none, optional parameter
# | Same as <code>display_name</code>, but search based on user id instead of display name. When both options are provided, <code>display_name</code> takes priority.
# | Integer; User id
# | none, optional parameter
# |-
# |<code>bbox</code>
# | 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
# |-
# |<code>from</code>
# |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 <code>created_at</code> or <code>updated_at</code> (specified by <code>sort</code>).
# | Date; Preferably in [https://wikipedia.org/wiki/ISO_8601 ISO 8601] format
# | none, optional parameter
# |-
# |<code>to</code>
# |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 <code>created_at</code> or <code>updated_at</code> (specified by <code>sort</code>). Only works when <code>from</code> is supplied.
# | Date; Preferably in [https://wikipedia.org/wiki/ISO_8601 ISO 8601] format
# | none, optional parameter
# |-
# |<code>sort</code>
# |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.
# |<code>created_at</code> or <code>updated_at</code>
# |<code>updated_at</code>
# | Sort results by creation or update date.
# | <code>created_at</code> or <code>updated_at</code>
# | <code>updated_at</code>
# |-
# |<code>order</code>
# |Specifies the order of the returned notes. It is possible to order them in ascending or descending order.
# |<code>oldest</code> or <code>newest</code>
# |<code>newest</code>
# | Sorting order. <code>oldest</code> is ascending order, <code>newest</code> is descending order.
# | <code>oldest</code> or <code>newest</code>
# | <code>newest</code>
# |}
#
### 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
Expand Down Expand Up @@ -653,9 +668,22 @@ osm_search_notes <- function(
#
# Gets an RSS feed for notes within an area.
#
# '''URL:''' <code>https://api.openstreetmap.org/api/0.6/notes/feed?bbox=''left'',''bottom'',''right'',''top''</code>
# '''URL:''' <code>https://api.openstreetmap.org/api/0.6/notes/feed
#
# '''Return type:''' application/xml
#
# {| class="wikitable"
# |-
# ! Parameter
# ! Description
# ! Allowed values
# ! Default value
# |-
# |<code>bbox</code>
# | 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
#'
Expand Down
Loading

0 comments on commit 84d4907

Please sign in to comment.