Package 'osmapiR'

Description

Log in/out osmapiR.

Usage

authenticate_osmapi()

logout_osmapi()

Details

All functions that require authentication will trigger the log in if the session is not yet authenticated, so calling this function is not really needed. Use authenticate_osmapi to sign in before executing scripts that require authentication to avoid interruptions.

Value

For authenticate_osmapi, print the user and permissions of the connection and return invisibly the display name of the logged user. logout_osmapi clear the OAuth2 token and can be useful to change user.

See Also

Other API functions: osm_api_versions(), osm_capabilities(), osm_permissions(), set_osmapi_connection()

Examples

## Not run: 
authenticate_osmapi()
logout_osmapi()

## End(Not run)

Description

Available API versions

Usage

osm_api_versions()

Value

A character vector with the supported versions

See Also

Other API functions: authenticate_osmapi(), osm_capabilities(), osm_permissions(), set_osmapi_connection()

Examples

osm_api_versions()

Description

The following command returns:

• All nodes that are inside a given bounding box and any relations that reference them.

• All ways that reference at least one node that is inside a given bounding box, any relations that reference them [the ways], and any nodes outside the bounding box that the ways may reference.

• All relations that reference one of the nodes, ways or relations included due to the above rules. (Does ”'not”' apply recursively, see explanation below.)

Usage

osm_bbox_objects(bbox, format = c("R", "xml", "json"), tags_in_columns = FALSE)

Arguments

Details

Note that, while this command returns those relations that reference the aforementioned nodes and ways, the reverse is not true: it does not (necessarily) return all of the nodes and ways that are referenced by these relations. This prevents unreasonably-large result sets. For example, imagine the case where:

• There is a relation named "England" that references every node in England.

• The nodes, ways, and relations are retrieved for a bounding box that covers a small portion of England. While the result would include the nodes, ways, and relations as specified by the rules for the command, including the "England" relation, it would (fortuitously) not include every node and way in England. If desired, the nodes and ways referenced by the "England" relation could be retrieved by their respective IDs.

Also note that ways which intersect the bounding box but have no nodes within the bounding box will not be returned.

Value

If format = "R", returns a data frame with one OSM object per row. If format = "xml", returns a xml2::xml_document following the OSM_XML format. If format = "json", returns a list with a json structure following the OSM_JSON format.

Note

For downloading data for purposes other than editing or exploring the history of the objects, perhaps is better to use the Overpass API. A similar function to download OSM objects using Overpass, is implemented in the osmdata function opq().

See Also

Other get OSM objects' functions: osm_get_objects(), osm_history_object(), osm_relations_object(), osm_ways_node(), osmapi_objects()

Examples

map_data <- osm_bbox_objects(bbox = c(1.8366775, 41.8336843, 1.8379971, 41.8344537))
## bbox as a character value also works (bbox = "1.8366775,41.8336843,1.8379971,41.8344537").
map_data

Description

Provide information about the capabilities and limitations of the current API.

Usage

osm_capabilities()

Details

API:

• version minimum and maximum are the API call versions that the server will accept.

• area maximum is the maximum area in square degrees that can be queried by API calls.

• tracepoints per_page is the maximum number of points in a single GPS trace. (Possibly incorrect)

• waynodes maximum is the maximum number of nodes that a way may contain.

• relationmember maximum is the maximum number of members that a relation may contain.

• 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 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).

Policy:

• Imagery blacklist lists all aerial and map sources, which are not permitted for OSM usage due to copyright. Editors must not show these resources as background layer.

Value

A list with the API capabilities and policies.

See Also

Other API functions: authenticate_osmapi(), osm_api_versions(), osm_permissions(), set_osmapi_connection()

Examples

osm_capabilities()

Description

Requires authentication.

Usage

osm_close_note(note_id)

osm_reopen_note(note_id)

Arguments

Value

Returns a data frame with the closed map notes (same format as osm_get_notes() with format = "R").

Functions

• osm_close_note(): Close notes as fixed.

• osm_reopen_note(): Reopen closed notes.

See Also

Other edit notes' functions: osm_create_comment_note(), osm_create_note(), osm_delete_note()

Examples

## Not run: 
set_osmapi_connection("testing") # use the testing server
note <- osm_create_note(lat = 41.38373, lon = 2.18233, text = "Testing osmapiR")
closed_note <- osm_close_note(note$id)
closed_note
reopened_note <- osm_reopen_note(note$id)
reopened_note
closed_note <- osm_close_note(note$id) # leave it closed

## End(Not run)

Description

Add a comment to a changeset and subscribe to the discussion. The changeset must be closed. Requires authentication.

Usage

osm_comment_changeset_discussion(changeset_id, comment)

Arguments

Value

Returns a data frame with the changeset (same format as osm_get_changesets() with format = "R").

See Also

Other changeset discussion's functions: osm_hide_comment_changeset_discussion(), osm_subscribe_changeset_discussion()

Examples

## Not run: 
set_osmapi_connection("testing") # use the testing server
changeset <- osm_get_changesets(300626)
updated_changeset <- osm_comment_changeset_discussion(
  changeset_id = changeset$id,
  comment = "A new comment to test osmapiR"
)
updated_changeset

## End(Not run)

Description

Create, update, or close a changeset

Usage

osm_create_changeset(
  comment,
  ...,
  created_by = paste("osmapiR", getOption("osmapir.osmapir_version")),
  verbose = FALSE
)

osm_update_changeset(
  changeset_id,
  comment,
  ...,
  created_by = paste("osmapiR", getOption("osmapir.osmapir_version")),
  verbose = FALSE
)

osm_close_changeset(changeset_id)

Arguments

Details

See https://wiki.openstreetmap.org/wiki/Changeset for details and the most common changeset's tags.

When updating a changeset, unchanged tags have to be repeated in order to not be deleted.

Value

The ID of the newly created changeset or a data.frame inheriting osmapi_changesets with the details of the updated changeset.

Nothing is returned upon successful closing of a changeset.

Functions

• osm_create_changeset(): Open a new changeset for editing.

• osm_update_changeset(): Update the tags of an open changeset.

• osm_close_changeset(): Close a changeset. A changeset may already have been closed without the owner issuing this API call. In this case an error code is returned.

See Also

Other edit changeset's functions: osm_diff_upload_changeset()

Examples

## Not run: 
set_osmapi_connection("testing") # use the testing server

chset_id <- osm_create_changeset(
  comment = "Describe the changeset",
  source = "GPS;survey",
  hashtags = "#testing;#osmapiR"
)

chaset <- osm_read_changeset(changeset_id = chset_id)
chaset

upd_chaset <- osm_update_changeset(
  changeset_id = chset_id,
  comment = "Improved description of the changeset",
  hashtags = "#testing;#osmapiR"
)
upd_chaset

## End(Not run)

Description

Add a new comment to an existing note. Requires authentication.

Usage

osm_create_comment_note(note_id, text)

Arguments

Value

Returns a data frame with the map note and the new comment (same format as osm_get_notes() with format = "R").

See Also

Other edit notes' functions: osm_close_note(), osm_create_note(), osm_delete_note()

Examples

## Not run: 
set_osmapi_connection("testing") # use the testing server
note <- osm_get_notes(53726)
updated_note <- osm_create_comment_note(note$id, text = "A new comment to the note")
updated_note

## End(Not run)

Description

Use this to upload a GPX file or archive of GPX files. Requires authentication.

Usage

osm_create_gpx(
  file,
  description,
  tags,
  visibility = c("private", "public", "trackable", "identifiable")
)

Arguments

Details

Note that for successful processing, the file must contain trackpoints (⁠<trkpt>⁠), 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.

Value

A number representing the ID of the new gpx.

See Also

Other edit GPS traces' functions: osm_delete_gpx(), osm_update_gpx()

Examples

vignette("how_to_edit_gps_traces", package = "osmapiR")

Description

Create a new note

Usage

osm_create_note(lat, lon, text, authenticate = TRUE)

Arguments

Details

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.

Value

Returns a data frame with the map note (same format as osm_get_notes() with format = "R").

See Also

Other edit notes' functions: osm_close_note(), osm_create_comment_note(), osm_delete_note()

Examples

## Not run: 
set_osmapi_connection("testing") # use the testing server
new_note <- osm_create_note(lat = 41.38373, lon = 2.18233, text = "Testing osmapiR")
new_note

## End(Not run)

Description

Creates a new element in an open changeset as specified.

Usage

osm_create_object(x, changeset_id)

Arguments

Details

If x is a data.frame, the columns type, changeset, tags must be present + column members for ways and relations + lat and lon for nodes. For the xml format, see the OSM wiki.

If multiple elements are provided only the first is created. The rest is discarded.

Value

The ID of the newly created OSM object.

Note

• This updates the bounding box of the changeset.

• The role attribute for relations is optional. An empty string is the default.

• To avoid performance issues when uploading multiple objects, the use of the osm_diff_upload_changeset() is highly recommended.

• The version of the created object will be 1.

See Also

Other edit OSM objects' functions: osm_delete_object(), osm_update_object()

Examples

vignette("how_to_edit_osm", package = "osmapiR")

Description

Use this to delete GPX files. Only usable by the owner account. Requires authentication.

Usage

osm_delete_gpx(gpx_id)

Arguments

Value

Returns NULL invisibly.

See Also

Other edit GPS traces' functions: osm_create_gpx(), osm_update_gpx()

Examples

vignette("how_to_edit_gps_traces", package = "osmapiR")

Description

Hide (delete) notes. This request needs to be done as an authenticated user with moderator role.

Usage

osm_delete_note(note_id, text)

Arguments

Details

Use osm_reopen_note() to make the note visible again.

Value

Returns a data frame with the hided map notes (same format as osm_get_notes() with format = "R").

See Also

Other edit notes' functions: osm_close_note(), osm_create_comment_note(), osm_create_note()

Other functions for moderators: osm_hide_comment_changeset_discussion(), osm_redaction_object()

Examples

## Not run: 
set_osmapi_connection("testing") # use the testing server
note <- osm_create_note(lat = "40.7327375", lon = "0.1702526", text = "Test note to delete.")
del_note <- osm_delete_note(note_id = note$id, text = "Hide note")
del_note

## End(Not run)

Description

Expects a valid XML representation of the element to be deleted.

Usage

osm_delete_object(x, changeset_id)

Arguments

Details

The version must match the version of the element you downloaded and the changeset must match the id of an open changeset owned by the current authenticated user. It is allowed, but not necessary, to have tags on the element except for lat/long which are required for nodes, without lat+lon the server gives 400 Bad request.

If x is a data.frame, the columns type, id, version and changeset must be present + lat and lon for nodes. For the xml format, see the OSM wiki.

If multiple elements are provided only the first is deleted. The rest is discarded.

Value

Returns the new version number of the object.

Note

• This updates the bounding box of the changeset.

• To avoid performance issues when deleting multiple objects, the use of the osm_diff_upload_changeset() is highly recommended. This is also the only way to ensure that multiple objects are updated in a single database transaction.

See Also

Other edit OSM objects' functions: osm_create_object(), osm_update_object()

Examples

vignette("how_to_edit_osm", package = "osmapiR")

Description

You can get the home location, the display name of the user and other details.

Usage

osm_details_logged_user(format = c("R", "xml", "json"))

Arguments

Value

If format = "R", returns a list with the user details.

format = "xml"

Returns a xml2::xml_document with the following format:

<osm version="0.6" generator="OpenStreetMap server">
  <user display_name="Max Muster" account_created="2006-07-21T19:28:26Z" id="1234">
    <contributor-terms agreed="true" pd="true"/>
    <img href="https://www.openstreetmap.org/attachments/users/images/000/000/1234/original/someLongURLOrOther.JPG"/>
    <roles></roles>
    <changesets count="4182"/>
    <traces count="513"/>
    <blocks>
      <received count="0" active="0"/>
    </blocks>
    <home lat="49.4733718952806" lon="8.89285988577866" zoom="3"/>
    <description>The description of your profile</description>
    <languages>
      <lang>de-DE</lang>
      <lang>de</lang>
      <lang>en-US</lang>
      <lang>en</lang>
    </languages>
    <messages>
      <received count="1" unread="0"/>
      <sent count="0"/>
    </messages>
  </user>
</osm>

format = "json"

{
 "version": "0.6",
 "generator": "OpenStreetMap server",
 "user": {
  "id": 1234,
  "display_name": "Max Muster",
  "account_created": "2006-07-21T19:28:26Z",
  "description": "The description of your profile",
  "contributor_terms": {"agreed": True, "pd": True},
  "img": {"href": "https://www.openstreetmap.org/attachments/users/images/000/000/1234/original/someLongURLOrOther.JPG"},
  "roles": [],
  "changesets": {"count": 4182},
  "traces": {"count": 513},
  "blocks": {"received": {"count": 0, "active": 0}},
  "home": {"lat": 49.4733718952806, "lon": 8.89285988577866, "zoom": 3},
  "languages": ["de-DE", "de", "en-US", "en"],
  "messages": {"received": {"count": 1, "unread": 0},
  "sent": {"count": 0}}
 }
}

See Also

Other users' functions: osm_get_preferences_user(), osm_get_user_details()

Examples

## Not run: 
usr_details <- osm_details_logged_user()
usr_details

## End(Not run)

Description

With this API call files in the OsmChange format can be uploaded to the server. This is guaranteed to be running in a transaction. So either all the changes are applied or none.

Usage

osm_diff_upload_changeset(changeset_id, osmcha, format = c("R", "xml"))

Arguments

Details

To upload an OSC file it has to conform to the OsmChange specification with the following differences:

• each element must carry a changeset and a version attribute (xml) / column (data.frame), except when you are creating an element where the version is not required as the server sets that for you. The changeset must be the same as the changeset ID being uploaded to.

• a ⁠<delete>⁠ block in the OsmChange document may have an ⁠if-unused⁠ attribute (the value of which is ignored) (action_type column with ⁠delete if-unused⁠ for data.frames). If this attribute is present, then the delete operation(s) in this block are conditional and will only be executed if the object to be deleted is not used by another object. Without the ⁠if-unused⁠, such a situation would lead to an error, and the whole diff upload would fail. Setting the attribute will also cause deletions of already deleted objects to not generate an error.

• OsmChange documents generally have user and uid attributes on each element. These are not required in the document uploaded to the API.

Value

If a diff is successfully applied and format = "R", it returns a data frame with one row for each edited object. For format = "xml", a xml2::xml_document is returned in the following format:

<diffResult generator="OpenStreetMap Server" version="0.6">
	<node|way|relation old_id="#" new_id="#" new_version="#"/>
	...
</diffResult>

with one element for every object in the upload.

Note that this can be counter-intuitive when the same element has appeared multiple times in the input then it will appear multiple times in the output.

Note

• Processing stops at the first error, so if there are multiple conflicts in one diff upload, only the first problem is reported.

• Refer to osm_capabilities() –> changesets$maximum_elements for the maximum number of changes permitted in a changeset.

• There is currently no limit in the diff size on the Rails port. CGImap limits diff size to 50MB (uncompressed size).

• Forward referencing of placeholder ids is not permitted and will be rejected by the API.

See Also

Other edit changeset's functions: osm_create_changeset()

Other OsmChange's functions: osm_download_changeset(), osmchange_create(), osmchange_delete(), osmchange_modify()

Examples

vignette("how_to_edit_osm", package = "osmapiR")

Description

Returns the OsmChange document describing all changes associated with the changeset.

Usage

osm_download_changeset(changeset_id, format = c("R", "osc", "xml"))

Arguments

Details

• The result of calling this may change as long as the changeset is open.

• The elements in the OsmChange are sorted by timestamp and version number.

• There is osm_get_changesets() to get only information about the changeset itself.

Value

If format = "R", returns a data frame with one row for each edit action in the changeset. If format = "osc", returns a xml2::xml_document in the OsmChange format.

See Also

Other get changesets' functions: osm_get_changesets(), osm_query_changesets()

Other OsmChange's functions: osm_diff_upload_changeset(), osmchange_create(), osmchange_delete(), osmchange_modify()

Examples

chaset <- osm_download_changeset(changeset_id = 137003062)
chaset

Description

RSS Feed of notes in a bbox

Usage

osm_feed_notes(bbox)

Arguments

Value

Returns a xml2::xml_document in the RSS format.

See Also

Other get notes' functions: osm_get_notes(), osm_read_bbox_notes(), osm_search_notes()

Examples

feed_notes <- osm_feed_notes(bbox = c(0.8205414, 40.6686604, 0.8857727, 40.7493377))
## bbox as a character value also works (bbox = "0.8205414,40.6686604,0.8857727,40.7493377").
feed_notes

Description

Returns the changesets with the given changeset_id.

Usage

osm_get_changesets(
  changeset_id,
  include_discussion = FALSE,
  format = c("R", "sf", "xml", "json"),
  tags_in_columns = FALSE
)

Arguments

Details

• The uid might not be available for changesets auto generated by the API v0.5 to API v0.6 transition

• The bounding box attributes will be missing for an empty changeset.

• The changeset bounding box is a rectangle that contains the bounding boxes of all objects changed in this changeset. It is not necessarily the smallest possible rectangle that does so.

• This API call only returns information about the changeset itself but not the actual changes made to elements in this changeset. To access this information use osm_download_changeset().

Value

If format = "R", returns a data frame with one OSM changeset per row. If format = "sf", returns a sf object from sf.

format = "xml"

Returns a xml2::xml_document with the following format:

<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:

{
  "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"
        }
      ]
    },
    ...
  ]
}

See Also

Other get changesets' functions: osm_download_changeset(), osm_query_changesets()

Examples

chaset <- osm_get_changesets(changeset_id = 137595351, include_discussion = TRUE)
chaset
chaset$discussion

Description

Use this to download the full GPX file. Private and trackable traces are only available by the owner account. Requires authentication.

Usage

osm_get_data_gpx(gpx_id, format)

Arguments

Value

If missing format, returns a xml2::xml_document with the original file data. If format = "R", returns a data frame with one point per row and the attributes extracted from the xml response. If format = "sf*", returns a sf object from sf (see st_as_sf() for details). If format = "gpx", returns a xml2::xml_document in the GPX format. If format = "xml", returns a xml2::xml_document in an undocumented format.

Note

If you request refers to a multi-file archive the response when you force gpx or xml format will consist of a non-standard simple concatenation of the files.

Extended data following schema ⁠http://www.garmin.com/xmlschemas/TrackPointExtension/v1⁠ in gpx files will be extracted for format = "R" and format = "sf_points", but lost for format = "sf_line".

See Also

Other get GPS' functions: osm_get_gpx_metadata(), osm_get_points_gps(), osm_list_gpxs()

Examples

## Not run: 
trk_data <- osm_get_data_gpx(gpx_id = 3498170, format = "R")
trk_data

## get attributes
attr(trk_data, "track")
attr(trk_data, "gpx_attributes")

## End(Not run)

Description

Use this to access the metadata about GPX files. Available without authentication if the file is marked public. Otherwise only usable by the owner account and requires authentication.

Usage

osm_get_gpx_metadata(gpx_id, format = c("R", "sf", "xml"))

Arguments

Value

If format = "R", returns a data frame with one trace per row. If format = "sf", returns a sf object from sf. If format = "xml", returns a xml2::xml_document with the following format:

<?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" 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>
    ...
  </gpx_file>
</osm>

See Also

Other get GPS' functions: osm_get_data_gpx(), osm_get_points_gps(), osm_list_gpxs()

Examples

## Not run: 
trk_meta <- osm_get_gpx_metadata(gpx_id = 3498170)
trk_meta

## End(Not run)

Description

Returns the existing note with the given ID.

Usage

osm_get_notes(note_id, format = c("R", "sf", "xml", "rss", "json", "gpx"))

Arguments

Value

If format = "R", returns a data frame with one map note per row. If format = "sf", returns a sf object from sf.

format = "xml"

Returns a xml2::xml_document with the following format:

<?xml version="1.0" encoding="UTF-8"?>
<osm version="0.6" generator="OpenStreetMap server" copyright="OpenStreetMap and contributors" attribution="https://www.openstreetmap.org/copyright" license="https://opendatacommons.org/licenses/odbl/1-0/">
  <note lon="0.1000000" lat="51.0000000">
    <id>16659</id>
    <url>https://master.apis.dev.openstreetmap.org/api/0.6/notes/16659</url>
    <comment_url>https://master.apis.dev.openstreetmap.org/api/0.6/notes/16659/comment</comment_url>
    <close_url>https://master.apis.dev.openstreetmap.org/api/0.6/notes/16659/close</close_url>
    <date_created>2019-06-15 08:26:04 UTC</date_created>
    <status>open</status>
    <comments>
      <comment>
        <date>2019-06-15 08:26:04 UTC</date>
        <uid>1234</uid>
        <user>userName</user>
        <user_url>https://master.apis.dev.openstreetmap.org/user/userName</user_url>
        <action>opened</action>
        <text>ThisIsANote</text>
        <html>&lt;p&gt;ThisIsANote&lt;/p&gt;</html>
      </comment>
      ...
    </comments>
  </note>
  ...
</osm>

format = "json"

Returns a list with the following json structure:

{
 "type": "FeatureCollection",
 "features": [
  {
   "type": "Feature",
   "geometry": {"type": "Point", "coordinates": [0.1000000, 51.0000000]},
   "properties": {
    "id": 16659,
    "url": "https://master.apis.dev.openstreetmap.org/api/0.6/notes/16659.json",
    "comment_url": "https://master.apis.dev.openstreetmap.org/api/0.6/notes/16659/comment.json",
    "close_url": "https://master.apis.dev.openstreetmap.org/api/0.6/notes/16659/close.json",
    "date_created": "2019-06-15 08:26:04 UTC",
    "status": "open",
    "comments": [
     {"date": "2019-06-15 08:26:04 UTC", "uid": 1234, "user": "userName", "user_url": "https://master.apis.dev.openstreetmap.org/user/userName", "action": "opened", "text": "ThisIsANote", "html": "<p>ThisIsANote</p>"},
     ...
    ]
   }
  }
 ]
}

format = "rss" & format = "gpx"

For format in "rss", and "gpx", a xml2::xml_document with the corresponding format.

See Also

Other get notes' functions: osm_feed_notes(), osm_read_bbox_notes(), osm_search_notes()

Examples

note <- osm_get_notes(note_id = "2067786")
note

Description

Retrieve objects by type, id and version.

Usage

osm_get_objects(
  osm_type,
  osm_id,
  version,
  full_objects = FALSE,
  format = c("R", "xml", "json"),
  tags_in_columns = FALSE
)

Arguments

Details

full_objects = TRUE does not support specifying version. For ways, full_objects = TRUE implies that it will return the way specified plus all nodes referenced by the way. For a relation, it will return the following:

• The relation itself

• All nodes, ways, and relations that are members of the relation

• Plus all nodes used by ways from the previous step

• The same recursive logic is not applied to relations. This means: If relation r1 contains way w1 and relation r2, and w1 contains nodes n1 and n2, and r2 contains node n3, then a "full" request for r1 will give you r1, r2, w1, n1, and n2. Not n3.

Value

If format = "R", returns a data frame with one OSM object per row. If format = "xml", returns a xml2::xml_document following the OSM_XML format. If format = "json", returns a list with a json structure following the OSM_JSON format.

Objects are sorted in the same order than osm_id except for full_objects = TRUE, where the nodes comes first, then ways, and relations at the end as specified by OSM_XML format.

Note

For downloading data for purposes other than editing or exploring the history of the objects, perhaps is better to use the Overpass API. A similar function to download OSM objects by type and id using Overpass, is implemented in the osmdata function opq_osm_id().

See Also

Other get OSM objects' functions: osm_bbox_objects(), osm_history_object(), osm_relations_object(), osm_ways_node(), osmapi_objects()

Examples

obj <- osm_get_objects(
  osm_type = c("node", "way", "way", "relation", "relation", "node"),
  osm_id = c("35308286", "13073736", "235744929", "40581", "341530", "1935675367"),
  version = c(1, 3, 2, 5, 7, 1)
)
obj

Description

Use this to retrieve the GPS track points that are inside a given bounding box (formatted in a GPX format).

Usage

osm_get_points_gps(
  bbox,
  page_number = 0,
  format = c("R", "sf", "sf_lines", "sf_points", "gpx")
)

Arguments

Value

If format = "R", returns a list of data frames with the points for each trace. For public and identifiable traces, the data frame include the attributes track_url, track_name, and track_desc. If format = "sf_lines", returns a sf object from sf. For format = "sf_points", returns a list of sf object (see st_as_sf() for details).

format = "gpx"

Returns a xml2::xml_document with the following format:

<?xml version="1.0" encoding="UTF-8"?>
<gpx version="1.0" creator="OpenStreetMap.org" xmlns="http://www.topografix.com/GPX/1/0">
  <trk>
    <name>20190626.gpx</name>
    <desc>Footpaths near Blackweir Pond, Epping Forest</desc>
    <url>https://api.openstreetmap.org/user/John%20Leeming/traces/3031013</url>
    <trkseg>
      <trkpt lat="51.6616100" lon="0.0534560">
        <time>2019-06-26T14:27:58Z</time>
      </trkpt>
      ...
    </trkseg>
    ...
  </trk>
  ...
</gpx>

• This response is NOT wrapped in an OSM xml parent element.

• The file format is GPX Version 1.0 which is not the current version. Verify that your tools support it.

Note

In violation of the GPX standard when downloading public GPX traces through the API, all waypoints of non-trackable traces are randomized (or rather sorted by lat/lon) and delivered as one trackSegment for privacy reasons. Trackable traces are delivered, sorted by descending upload time, before the waypoints of non-trackable traces.

Private traces without name, desc and url can be separated in different items in the result if they get split due to server pagination. Public traces are united using matching URL.

See Also

Other get GPS' functions: osm_get_data_gpx(), osm_get_gpx_metadata(), osm_list_gpxs()

Examples

pts_gps <- osm_get_points_gps(bbox = c(-0.3667545, 40.2153246, -0.3354263, 40.2364915))
## bbox as a character value also works (bbox = "-0.3667545,40.2153246,-0.3354263,40.2364915").
pts_gps

## get attributes
lapply(pts_gps, function(x) attributes(x)[c("track_url", "track_name", "track_desc")])
attr(pts_gps, "gpx_attributes")

Description

Get or set preferences for the logged-in user

Usage

osm_get_preferences_user(key, format = c("R", "xml", "json"))

osm_set_preferences_user(key, value, all_prefs)

Arguments

Details

The sizes of the key and value are limited to 255 characters.

The OSM server supports storing arbitrary user preferences. This can be used by editors, for example, to offer the same configuration wherever the user logs in, instead of a locally-stored configuration. For an overview of applications using the preferences-API and which key-schemes they use, see this wiki page.

Value

If format = "R", returns a data frame with key and value columns of the user preferences.

format = "xml"

Returns a xml2::xml_document with the following format:

<osm version="0.6" generator="OpenStreetMap server">
  <preferences>
    <preference k="somekey" v="somevalue" />
    ...
  </preferences>
</osm>

format = "json"

Returns a list with the following json structure:

{
 "version": "0.6",
 "generator": "OpenStreetMap server",
 "preferences": {"somekey": "somevalue, ...}
}

Set preferences

Nothing is returned upon successful setting of user preferences.

See Also

Other users' functions: osm_details_logged_user(), osm_get_user_details()

Examples

## Not run: 
prefs_ori <- osm_get_preferences_user()
prefs_ori


osm_set_preferences_user(key = "osmapiR-test", value = "good!")
osm_get_preferences_user(key = "osmapiR-test")

osm_set_preferences_user(key = "osmapiR-test", value = NULL) # Delete pref

## Restore all preferences
osm_set_preferences_user(all_prefs = prefs_ori)

## End(Not run)

Description

Details of users

Usage

osm_get_user_details(user_id, format = c("R", "xml", "json"))

Arguments

Value

For users not found, the result is empty. If format = "R", returns a data frame with one user per row.

format = "xml"

Returns a xml2::xml_document with the following format:

<osm version="0.6" generator="OpenStreetMap server">
  <user id="12023" display_name="jbpbis" account_created="2007-08-16T01:35:56Z">
    <description></description>
    <contributor-terms agreed="false"/>
    <img href="http://www.gravatar.com/avatar/c8c86cd15f60ecca66ce2b10cb6b9a00.jpg?s=256&amp;d=http%3A%2F%2Fwww.openstreetmap.org%2Fassets%2Fusers%2Fimages%2Flarge-39c3a9dc4e778311af6b70ddcf447b58.png"/>
    <roles>
    </roles>
    <changesets count="1"/>
    <traces count="0"/>
    <blocks>
      <received count="0" active="0"/>
    </blocks>
  </user>
  <user id="210447" display_name="siebh" account_created="2009-12-20T10:11:42Z">
    <description></description>
    <contributor-terms agreed="true"/>
    <roles>
    </roles>
    <changesets count="267"/>
    <traces count="1"/>
    <blocks>
      <received count="0" active="0"/>
    </blocks>
  </user>
</osm>

format = "json"

Returns a list with the following json structure:

{
 "version": "0.6",
 "generator": "OpenStreetMap server",
 "users": [
  {"user": {"id": 12023, "display_name": "jbpbis", "account_created": "2007-08-16T01:35:56Z", "description": "", "contributor_terms": {"agreed": False}, "roles": [], "changesets": {"count": 1}, "traces": {"count": 0}, "blocks": {"received": {"count": 0, "active": 0}}}},
  {"user": {"id": 210447, "display_name": "siebh", "account_created": "2009-12-20T10:11:42Z", "description": "", "contributor_terms": {"agreed": True}, "roles": [], "changesets": {"count": 363}, "traces": {"count": 1}, "blocks": {"received": {"count": 0, "active": 0}}}}
 ]
}

See Also

Other users' functions: osm_details_logged_user(), osm_get_preferences_user()

Examples

usrs <- osm_get_user_details(user_id = c(1, 24, 44, 45, 46, 48, 49, 50))
usrs

Description

This request needs to be done as an authenticated user with moderator role.

Usage

osm_hide_comment_changeset_discussion(comment_id)

osm_unhide_comment_changeset_discussion(comment_id)

Arguments

Value

Returns a data frame with the changeset (same format as osm_get_changesets() with format = "R").

Functions

• osm_hide_comment_changeset_discussion(): Sets visible flag on changeset comment to false.

• osm_unhide_comment_changeset_discussion(): Sets visible flag on changeset comment to true.

See Also

Other changeset discussion's functions: osm_comment_changeset_discussion(), osm_subscribe_changeset_discussion()

Other functions for moderators: osm_delete_note(), osm_redaction_object()

Examples

## Not run: 
chdis <- osm_get_changesets("265646", include_discussion = TRUE)
hide_com <- osm_hide_comment_changeset_discussion(comment_id = chdis$discussion[[1]]$id[1])
unhide_com <- osm_unhide_comment_changeset_discussion(comment_id = chdis$discussion[[1]]$id[1])

## End(Not run)

Description

Retrieves all old versions of an object from OSM, sorted by version number from oldest to newest.

Usage

osm_history_object(
  osm_type = c("node", "way", "relation"),
  osm_id,
  format = c("R", "xml", "json"),
  tags_in_columns = FALSE
)

Arguments

Value

If format = "R", returns a data frame with a version of the OSM object per row. If format = "xml", returns a xml2::xml_document following the OSM_XML format. If format = "json", returns a list with a json structure following the OSM_JSON format.

See Also

Other get OSM objects' functions: osm_bbox_objects(), osm_get_objects(), osm_relations_object(), osm_ways_node(), osmapi_objects()

Examples

node <- osm_history_object(osm_type = "node", osm_id = 35308286)
node

way <- osm_history_object(osm_type = "way", osm_id = 13073736L)
way

rel <- osm_history_object(osm_type = "relation", osm_id = "40581")
rel

Description

Use this to get a list of GPX traces owned by the authenticated user. Requires authentication.

Usage

osm_list_gpxs(format = c("R", "sf", "xml"))

Arguments

Value

Results with the same format as osm_get_gpx_metadata(). If format = "R", returns a data frame with one trace per row. If format = "sf", returns a sf object from sf. If format = "xml", returns a xml2::xml_document. Example:

<?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" 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>

See Also

Other get GPS' functions: osm_get_data_gpx(), osm_get_gpx_metadata(), osm_get_points_gps()

Examples

## Not run: 
traces <- osm_list_gpxs()
traces

## End(Not run)

Description

Returns the permissions granted to the current API connection.

Usage

osm_permissions(format = c("R", "xml", "json"))

Arguments

Details

Currently the following permissions can appear in the result, corresponding directly to the ones used in the OAuth 1.0a application definition:

• allow_read_prefs (read user preferences)

• allow_write_prefs (modify user preferences)

• allow_write_diary (create diary entries, comments and make friends)

• allow_write_api (modify the map)

• allow_write_redactions (redact element versions)

• allow_read_gpx (read private GPS traces)

• allow_write_gpx (upload GPS traces)

• allow_write_notes (modify notes)

Value

If the API client is not authorized, an empty list of permissions will be returned. Otherwise, the list will be based on the granted scopes of the logged user.

Note

For compatibility reasons, all OAuth 2.0 scopes will be prefixed by "allow_", e.g. scope "read_prefs" will be shown as permission "allow_read_prefs".

See Also

Other API functions: authenticate_osmapi(), osm_api_versions(), osm_capabilities(), set_osmapi_connection()

Examples

## Not run: 
perms <- osm_permissions()
perms

## End(Not run)

Description

This is an API method for querying changesets. It supports querying by different criteria.

Usage

osm_query_changesets(
  bbox,
  user,
  time,
  time_2,
  from,
  to,
  open,
  closed,
  changeset_ids,
  order = c("newest", "oldest"),
  limit = getOption("osmapir.api_capabilities")$api$changesets["default_query_limit"],
  format = c("R", "sf", "xml", "json"),
  tags_in_columns = FALSE
)

Arguments

Details

Where multiple queries are given the result will be those which match all of the requirements. The contents of the returned document are the changesets and their tags. To get the full set of changes associated with a changeset, use osm_download_changeset() on each changeset ID individually.

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 ordered by created_at – see the current state). Reverse ordering cannot be combined with time.

Te valid formats for time, time_2, from and to parameters are POSIXt values or characters with anything that Time.parse Ruby function will parse.

Value

If format = "R", returns a data frame with one OSM changeset per row. If format = "sf", returns a sf object from sf.

format = "xml"

Returns a xml2::xml_document with the following format:

<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:

{
  "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"
      }
    },
    ...
  ]
}

See Also

Other get changesets' functions: osm_download_changeset(), osm_get_changesets()

Examples

chst_ids <- osm_query_changesets(changeset_ids = c(137627129, 137625624))
chst_ids

chsts <- osm_query_changesets(
  bbox = c(-1.241112, 38.0294955, 8.4203171, 42.9186456),
  user = "Mementomoristultus",
  time = "2023-06-22T02:23:23Z",
  time_2 = "2023-06-22T00:38:20Z"
)
chsts

chsts2 <- osm_query_changesets(
  bbox = c("-9.3015367,41.8073642,-6.7339533,43.790422"),
  user = "Mementomoristultus",
  closed = TRUE
)
chsts2

Description

Returns the existing notes in the specified bounding box. The notes will be ordered by the date of their last change, the most recent one will be first.

Usage

osm_read_bbox_notes(
  bbox,
  limit = 100,
  closed = 7,
  format = c("R", "sf", "xml", "rss", "json", "gpx")
)

Arguments

Value

If format = "R", returns a data frame with one map note per row. If format = "sf", returns a sf object from sf.

format = "xml"

Returns a xml2::xml_document with the following format:

<?xml version="1.0" encoding="UTF-8"?>
<osm version="0.6" generator="OpenStreetMap server" copyright="OpenStreetMap and contributors" attribution="https://www.openstreetmap.org/copyright" license="https://opendatacommons.org/licenses/odbl/1-0/">
  <note lon="0.1000000" lat="51.0000000">
    <id>16659</id>
    <url>https://master.apis.dev.openstreetmap.org/api/0.6/notes/16659</url>
    <comment_url>https://master.apis.dev.openstreetmap.org/api/0.6/notes/16659/comment</comment_url>
    <close_url>https://master.apis.dev.openstreetmap.org/api/0.6/notes/16659/close</close_url>
    <date_created>2019-06-15 08:26:04 UTC</date_created>
    <status>open</status>
    <comments>
      <comment>
        <date>2019-06-15 08:26:04 UTC</date>
        <uid>1234</uid>
        <user>userName</user>
        <user_url>https://master.apis.dev.openstreetmap.org/user/userName</user_url>
        <action>opened</action>
        <text>ThisIsANote</text>
        <html>&lt;p&gt;ThisIsANote&lt;/p&gt;</html>
      </comment>
      ...
    </comments>
  </note>
  ...
</osm>

format = "json"

Returns a list with the following json structure:

{
 "type": "FeatureCollection",
 "features": [
  {
   "type": "Feature",
   "geometry": {"type": "Point", "coordinates": [0.1000000, 51.0000000]},
   "properties": {
    "id": 16659,
    "url": "https://master.apis.dev.openstreetmap.org/api/0.6/notes/16659.json",
    "comment_url": "https://master.apis.dev.openstreetmap.org/api/0.6/notes/16659/comment.json",
    "close_url": "https://master.apis.dev.openstreetmap.org/api/0.6/notes/16659/close.json",
    "date_created": "2019-06-15 08:26:04 UTC",
    "status": "open",
    "comments": [
     {"date": "2019-06-15 08:26:04 UTC", "uid": 1234, "user": "userName", "user_url": "https://master.apis.dev.openstreetmap.org/user/userName", "action": "opened", "text": "ThisIsANote", "html": "<p>ThisIsANote</p>"},
     ...
    ]
   }
  }
 ]
}

format = "rss" & format = "gpx"

For format in "rss", and "gpx", a xml2::xml_document with the corresponding format.

Note

The comment properties (uid, user, user_url) will be omitted if the comment was anonymous.

See Also

Other get notes' functions: osm_feed_notes(), osm_get_notes(), osm_search_notes()

Examples

notes <- osm_read_bbox_notes(bbox = c(3.7854767, 39.7837403, 4.3347931, 40.1011851), limit = 10)
## bbox as a character value also works (bbox = "3.7854767,39.7837403,4.3347931,40.1011851").
notes

Description

Used by the Data Working Group to hide old versions of elements containing data privacy or copyright infringements. Only permitted for OSM accounts with the moderator role (DWG and server admins).

Usage

osm_redaction_object(
  osm_type = c("node", "way", "relation"),
  osm_id,
  version,
  redaction_id
)

Arguments

Details

The redaction_id is listed on https://www.openstreetmap.org/redactions. More information can be found in the source.

Value

Nothing is returned upon successful redaction or unredaction of an object.

Note

Requires write_redactions OAuth scope; before September 2024 required either write_api or write_redactions, and before December 2023 required write_api; those older scope requirements may still be around on other openstreetmap-website-based servers such as OpenHistoricalMap.

See Also

Other functions for moderators: osm_delete_note(), osm_hide_comment_changeset_discussion()

Examples

## Not run: 
## WARNING: this example will edit the OSM (testing) DB with your user!
# You will need a user with moderator role in the server to use `osm_redaction_object()`
set_osmapi_connection(server = "testing") # setting https://master.apis.dev.openstreetmap.org
x <- data.frame(type = "node", lat = 0, lon = 0, name = "Test redaction.")
obj <- osmapi_objects(x, tag_columns = "name")
changeset_id <- osm_create_changeset(
  comment = "Test object redaction",
  hashtags = "#testing;#osmapiR"
)

node_id <- osm_create_object(x = obj, changeset_id = changeset_id)
node_osm <- osm_get_objects(osm_type = "node", osm_id = node_id)
deleted_version <- osm_delete_object(x = node_osm, changeset_id = changeset_id)
redaction <- osm_redaction_object(
  osm_type = node_osm$type, osm_id = node_osm$id, version = 1, redaction_id = 1
)
unredaction <- osm_redaction_object(osm_type = node_osm$type, osm_id = node_osm$id, version = 1)
osm_close_changeset(changeset_id = changeset_id)

## End(Not run)

Description

Returns all (not deleted) relations in which the given object is used.

Usage

osm_relations_object(
  osm_type = c("node", "way", "relation"),
  osm_id,
  format = c("R", "xml", "json"),
  tags_in_columns = FALSE
)

Arguments

Value

If format = "R", returns a data frame with one OSM object per row. If format = "xml", returns a xml2::xml_document following the OSM_XML format. If format = "json", returns a list with a json structure following the OSM_JSON format.

See Also

Other get OSM objects' functions: osm_bbox_objects(), osm_get_objects(), osm_history_object(), osm_ways_node(), osmapi_objects()

Examples

node <- osm_relations_object(osm_type = "node", osm_id = 152364165)
node

way <- osm_relations_object(osm_type = "way", osm_id = 372011578)
way

rel <- osm_relations_object(osm_type = "relation", osm_id = 342792)
rel

Description

Returns notes that match the specified query. If no query is provided, the most recently updated notes are returned.

Usage

osm_search_notes(
  q,
  user,
  bbox,
  from,
  to,
  closed = 7,
  sort = c("updated_at", "created_at"),
  order = c("newest", "oldest"),
  limit = getOption("osmapir.api_capabilities")$api$notes["default_query_limit"],
  format = c("R", "sf", "xml", "rss", "json", "gpx")
)

Arguments

Details

The notes will be ordered by the date of their last change, the most recent one will be first.

Value

If format = "R", returns a data frame with one map note per row. If format = "sf", returns a sf object from sf. If format = "json", returns a list with the json structure. For format in "xml", "rss", and "gpx", a xml2::xml_document with the corresponding format.

See Also

Other get notes' functions: osm_feed_notes(), osm_get_notes(), osm_read_bbox_notes()

Examples

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", bbox = c(-0.1594133, 40.5229822, 3.322251, 42.861523),
  closed = -1, format = "json"
)
my_notes

Description

Subscribe or unsubscribe to a changeset discussion

Usage

osm_subscribe_changeset_discussion(changeset_id)

osm_unsubscribe_changeset_discussion(changeset_id)

Arguments

Value

Returns the changeset information.

Functions

• osm_subscribe_changeset_discussion(): Subscribe to the discussion of a changeset to receive notifications for new comments.

• osm_unsubscribe_changeset_discussion(): Unsubscribe from the discussion of a changeset to stop receiving notifications.

See Also

Other changeset discussion's functions: osm_comment_changeset_discussion(), osm_hide_comment_changeset_discussion()

Examples

## Not run: 
# set_osmapi_connection(server = "openstreetmap.org")
osm_subscribe_changeset_discussion(137595351)
osm_unsubscribe_changeset_discussion("137595351")

## End(Not run)

Description

Use this to update a GPX info. Only usable by the owner account. Requires authentication.

Usage

osm_update_gpx(
  gpx_id,
  name,
  description,
  tags,
  visibility = c("private", "public", "trackable", "identifiable")
)

Arguments

Details

Missing arguments won't be updated.

Value

Returns a data frame with the updated metadata of the GPS trace. The same format that osm_get_gpx_metadata() with format = "R".

See Also

Other edit GPS traces' functions: osm_create_gpx(), osm_delete_gpx()

Examples

vignette("how_to_edit_gps_traces", package = "osmapiR")

Description

Updates data from a preexisting element.

Usage

osm_update_object(x, changeset_id)

Arguments

Details

A full representation of the element as it should be after the update has to be provided. Any tags, way-node refs, and relation members that remain unchanged must be in the update as well. A version number must be provided as well, it must match the current version of the element in the database.

If x is a data.frame, the columns type, id, visible, version, changeset, and tags must be present + column members for ways and relations + lat and lon for nodes. For the xml format, see the OSM wiki.

If multiple elements are provided only the first is updated. The rest is discarded.

Value

Returns the new version number of the object.

Note

• This updates the bounding box of the changeset.

• To avoid performance issues when updating multiple objects, the use of the osm_diff_upload_changeset() is highly recommended. This is also the only way to ensure that multiple objects are updated in a single database transaction.

See Also

Other edit OSM objects' functions: osm_create_object(), osm_delete_object()

Examples

vignette("how_to_edit_osm", package = "osmapiR")

Description

Returns all the (not deleted) ways in which the given node is used.

Usage

osm_ways_node(node_id, format = c("R", "xml", "json"), tags_in_columns = FALSE)

Arguments

Value

If format = "R", returns a data frame with one OSM object per row. If format = "xml", returns a xml2::xml_document following the OSM_XML format. If format = "json", returns a list with a json structure following the OSM_JSON format.

See Also

Other get OSM objects' functions: osm_bbox_objects(), osm_get_objects(), osm_history_object(), osm_relations_object(), osmapi_objects()

Examples

ways_node <- osm_ways_node(node_id = 35308286)
ways_node

Description

osmapi_objects constructor

Usage

osmapi_objects(x, tag_columns, keep_na_tags = FALSE)

Arguments

Value

An osmapi_objects

See Also

Other get OSM objects' functions: osm_bbox_objects(), osm_get_objects(), osm_history_object(), osm_relations_object(), osm_ways_node()

Examples

x <- data.frame(
  type = c("node", "node", "way"), id = 1:3, name = c(NA, NA, "My way")
)
x$members <- list(NULL, NULL, 1:2)
obj <- osmapi_objects(x, tag_columns = "name")
obj

Description

Prepare data to create OSM objects.

Usage

osmchange_create(x, format = c("R", "osc", "xml"))

Arguments

Details

Objects IDs are unknown and will be allocated by the server. If id column is missing in x, a negative placeholders will be used. Check OsmChange page for details about how to refer to objects still not created to define the members of relations and nodes of ways.

Value

If format = "R", returns a osmapi_OsmChange data frame with one OSM edition per row. If format = "osc" or format = "xml", returns a xml2::xml_document following the OsmChange format that can be saved with xml2::write_xml() and opened in other applications such as JOSM.

The results are ready to send the editions to the servers with osm_diff_upload_changeset().

See Also

Other OsmChange's functions: osm_diff_upload_changeset(), osm_download_changeset(), osmchange_delete(), osmchange_modify()

Examples

d <- data.frame(
  type = c("node", "node", "way", "relation"),
  id = -(1:4),
  lat = c(0, 1, NA, NA),
  lon = c(0, 1, NA, NA),
  name = c(NA, NA, "My way", "Our relation"),
  type.1 = c(NA, NA, NA, "Column clash!")
)
d$members <- list(
  NULL, NULL, -(1:2),
  matrix(
    c("node", "-1", NA, "node", "-2", NA, "way", "-3", "outer"),
    nrow = 3, ncol = 3, byrow = TRUE, dimnames = list(NULL, c("type", "ref", "role"))
  )
)
obj <- osmapi_objects(d, tag_columns = c(name = "name", type = "type.1"))
osmcha <- osmchange_create(obj)
osmcha

Description

Prepare data to delete OSM objects.

Usage

osmchange_delete(x, delete_if_unused = FALSE, format = c("R", "osc", "xml"))

Arguments

Details

If ⁠if-unused⁠ attribute is present, then the delete operation(s) in this block are conditional and will only be executed if the object to be deleted is not used by another object. Without the ⁠if-unused⁠, such a situation would lead to an error, and the whole diff upload would fail. Setting the attribute will also cause deletions of already deleted objects to not generate an error.

Value

If format = "R", returns a osmapi_OsmChange data frame with one OSM edition per row. If format = "osc" or format = "xml", returns a xml2::xml_document following the OsmChange format that can be saved with xml2::write_xml() and opened in other applications such as JOSM.

The results are ready to send the editions to the servers with osm_diff_upload_changeset().

See Also

Other OsmChange's functions: osm_diff_upload_changeset(), osm_download_changeset(), osmchange_create(), osmchange_modify()

Examples

obj_id <- osmapi_objects(data.frame(
  type = c("way", "way", "relation", "node"),
  id = c("722379703", "629132242", "8387952", "4739010921")
))
osmchange_del <- osmchange_delete(obj_id)

Description

Prepare data to update tags, members and/or latitude and longitude.

Usage

osmchange_modify(
  x,
  tag_keys,
  members = FALSE,
  lat_lon = FALSE,
  format = c("R", "osc", "xml")
)

Arguments

Details

x should be a osmapi_objects or follow the same format. Missing tags or tags with NA in the value will be removed if tag_keys is not specified. See osm_get_objects() for examples of the format.

Value

If format = "R", returns a osmapi_OsmChange data frame with one OSM edition per row. If format = "osc" or format = "xml", returns a xml2::xml_document following the OsmChange format that can be saved with xml2::write_xml() and opened in other applications such as JOSM.

The results are ready to send the editions to the servers with osm_diff_upload_changeset().

See Also

Other OsmChange's functions: osm_diff_upload_changeset(), osm_download_changeset(), osmchange_create(), osmchange_delete()

Examples

obj <- osm_get_objects(
  osm_type = c("node", "way", "way", "relation", "relation", "node"),
  osm_id = c("35308286", "13073736", "235744929", "40581", "341530", "1935675367"),
  version = c(1, 3, 2, 5, 7, 1) # Old versions
)
osmch <- osmchange_modify(obj)
osmch

Description

Functions to configure the connections. Probably, you should only use set_osmapi_connection.

Usage

set_osmapi_connection(
  server = c("openstreetmap.org", "testing"),
  cache_authentication
)

get_osmapi_url()

set_osmapi_url(osmapi_url)

Arguments

Details

When testing your software against the API you should consider using https://master.apis.dev.openstreetmap.org instead of the live-api (set_osmapi_connection("testing")). Your account for the live service is not in the same database, so you probably need a new username and password for the test service; please visit that page in a browser to sign up.

set_osmapi_url() and get_osmapi_url only deal with the API base URL. On the other hand, set_osmapi_connection also configure the authentication parameters needed for PUT, POST and DELETE calls.

For further details, see https://wiki.openstreetmap.org/wiki/API_v0.6.

Value

Configure .Options[grep("^osmapir\\.[a-z]+_(?!secret$)", names(.Options), perl = TRUE)] :) and return osmapir.base_api_url.

See Also

Other API functions: authenticate_osmapi(), osm_api_versions(), osm_capabilities(), osm_permissions()

Examples

ori <- get_osmapi_url()
set_osmapi_connection(server = "testing")
get_osmapi_url()
set_osmapi_connection(server = "openstreetmap.org")
get_osmapi_url()

## Restore options
if (ori == "https://api.openstreetmap.org") {
  set_osmapi_connection(server = "openstreetmap.org")
} else if (ori == "https://master.apis.dev.openstreetmap.org") {
  set_osmapi_connection(server = "testing")
} else {
  warning(
    "A non standard osmapiR connection detected (", ori,
    "). If you configured manually options like \"osmapir.base_api_url\" or \"osmapir.oauth_id\", ",
    "configure it again."
  )
}

Description

Convert osmapiR objects to sf objects

Usage

st_as_sf.osmapi_map_notes(x, ...)

st_as_sf.osmapi_changesets(x, ...)

st_as_sf.osmapi_gps_track(x, format = c("line", "points"), ...)

st_as_sf.osmapi_gpx(x, format = c("lines", "points"), ...)

Arguments

Value

Returns a sf object from sf package or a list of for osmapi_gpx and format = "points".

When x is a osmapi_gps_track or osmapi_gpx object and format = "line", the result will have XYZM dimensions for coordinates, elevation and time if available. In this format, time will loss the POSIXct type as only numeric For format = "points", the result will have XY dimensions and elevation and time will be independent columns if available.

See Also

st_as_sf() from sf package.

Other methods: tags_list2wide()

Examples

note <- osm_get_notes(note_id = "2067786")
sf::st_as_sf(note)

chaset <- osm_get_changesets(changeset_id = 137595351, include_discussion = TRUE)
sf::st_as_sf(chaset)

gpx <- osm_get_points_gps(bbox = c(-0.3667545, 40.2153246, -0.3354263, 40.2364915))
sf::st_as_sf(gpx, format = "line")
sf::st_as_sf(gpx, format = "points")

## Not run: 
# Requires authentication
trk <- osm_get_data_gpx(gpx_id = 3498170, format = "R")
sf::st_as_sf(trk, format = "line")
sf::st_as_sf(trk, format = "points")

## End(Not run)

Description

Objects of classes osmapi_objects and osmapi_changesets can represent the tags in a column with a list with a data.frame for each row with 2 columns for keys and values, or by columns for each key. These functions allow to change the format of the tags.

Usage

tags_list2wide(x)

tags_wide2list(x)

Arguments

Details

Both formats have advantages. Tags in a list of data.frames is a more compact representation and there is no risk of clashes of column names and tag keys. Tags in columns make it easier to select rows by tags as in a regular data.frame. Column name clashes are resolved and the original key names restored when transformed to tags list format.

By default, functions returning osmapi_objects or osmapi_changesets objects, use the the tags in a list column, but can return the results in a wide format using the parameter tags_in_columns = TRUE.

Value

A data frame with the same class and data than the original (osmapi_objects or osmapi_changesets) but with the specified tags' format.

See Also

Other methods: st_as_sf

Examples

peaks_wide <- osm_get_objects(
  osm_type = "node", osm_id = c(35308286, 1935675367), tags_in_columns = TRUE
)
peaks_list <- tags_wide2list(peaks_wide)

# tags in list format
peaks_list$tags

# Select peaks with `prominence` tag
peaks_wide[!is.na(peaks_wide$prominence), ]
peaks_list[sapply(peaks_list$tags, function(x) any(x$key == "prominence")), ]

cities_list <- osm_get_objects(osm_type = "relation", osm_id = c("40581", "341530"))
# Column name clash:
cities_wide <- tags_list2wide(cities_list)