osmdata is an R package for accessing the data
underlying OpenStreetMap (OSM), delivered via the Overpass
API. (Other packages such as OpenStreetMap
can be used to download raster tiles based on OSM data.) Overpass is a read-only API that
extracts custom selected parts of OSM data. Data can be returned in a
variety of formats, including as Simple Features
(sf), Spatial
(sp), or Silicate
(sc) objects. The package is designed to allow access
to small-to-medium-sized OSM datasets (see osmextract
for an approach for reading-in bulk OSM data extracts).
To install latest CRAN version:
install.packages ("osmdata")Alternatively, install the development version with any one of the following options:
# install.packages("remotes")
remotes::install_git ("https://git.sr.ht/~mpadge/osmdata")
remotes::install_bitbucket ("mpadge/osmdata")
remotes::install_gitlab ("mpadge/osmdata")
remotes::install_github ("ropensci/osmdata")To load the package and check the version:
library (osmdata)
#> Data (c) OpenStreetMap contributors, ODbL 1.0. https://www.openstreetmap.org/copyright
packageVersion ("osmdata")
#> [1] '0.2.5.68'Overpass
API queries can be built from a base query constructed with
opq followed by add_osm_feature. The
corresponding OSM objects are then downloaded and converted to Simple Feature
(sf) objects with osmdata_sf(), Spatial
(sp) objects with osmdata_sp()
(DEPRECATED) or Silicate
(sc) objects with osmdata_sc(). For
example,
x <- opq (bbox = c (-0.27, 51.47, -0.20, 51.50)) |> # Chiswick Eyot in London, U.K.
add_osm_feature (key = "name", value = "Thames", value_exact = FALSE) |>
osmdata_sf ()
x#> Object of class 'osmdata' with:
#> $bbox : 51.47,-0.27,51.5,-0.2
#> $overpass_call : The call submitted to the overpass API
#> $meta : metadata including timestamp and version numbers
#> $osm_points : 'sf' Simple Features Collection with 24548 points
#> $osm_lines : 'sf' Simple Features Collection with 2219 linestrings
#> $osm_polygons : 'sf' Simple Features Collection with 33 polygons
#> $osm_multilines : 'sf' Simple Features Collection with 6 multilinestrings
#> $osm_multipolygons : 'sf' Simple Features Collection with 3 multipolygonsOSM data can also be downloaded in OSM XML format with
osmdata_xml() and saved for use with other software.
osmdata_xml(q1, "data.osm")All osmdata queries begin with a bounding box defining
the area of the query. The getbb()
function can be used to extract bounding boxes for specified place
names.
getbb ("astana kazakhstan")
#> min max
#> x 71.21797 71.78519
#> y 50.85761 51.35111The next step is to convert that to an overpass query object with the
opq()
function:
q <- opq (getbb ("astana kazakhstan"))
q <- opq ("astana kazakhstan") # identical resultIt is also possible to use bounding polygons rather than rectangular boxes:
b <- getbb ("bangalore", format_out = "polygon")
class (b)
#> [1] "list"
str (b)
#> List of 1
#> $ relation/7902476:List of 1
#> ..$ outer: num [1:2605, 1:2] 77.5 77.5 77.5 77.5 77.5 ...The next step is to define features of interest using the add_osm_feature()
function. This function accepts key and
value parameters specifying desired features in the OSM key-vale
schema. Multiple add_osm_feature() calls may be
combined as illustrated below, with the result being a logical AND
operation, thus returning all amenities that are labelled both as
restaurants and also as pubs:
q <- opq ("portsmouth usa") |>
add_osm_feature (key = "amenity", value = "restaurant") |>
add_osm_feature (key = "amenity", value = "pub") # There are none of theseFeatures can also be requested by key only, in which case features with any values for the specified key will be returned:
q <- opq ("portsmouth usa") |>
add_osm_feature (key = "amenity")Such key-only queries can, however, translate into requesting very large data sets, and should generally be avoided in favour of more precise key-value specifications.
Negation can also be specified by pre-pending an exclamation mark so that the following requests all amenities that are NOT labelled as restaurants and that are not labelled as pubs:
q <- opq ("portsmouth usa") |>
add_osm_feature (key = "amenity", value = "!restaurant") |>
add_osm_feature (key = "amenity", value = "!pub") # There are a lot of theseAdditional arguments allow for more refined matching, such as the following request for all pubs with “irish” in the name:
q <- opq ("washington dc") |>
add_osm_feature (key = "amenity", value = "pub") |>
add_osm_feature (
key = "name", value = "irish",
value_exact = FALSE, match_case = FALSE
)Logical OR combinations can be constructed using the separate add_osm_features()
function. The first of the above examples requests all features that
are both restaurants AND pubs. The following query will request data on
restaurants OR pubs:
q <- opq ("portsmouth usa") |>
add_osm_features (features = c (
"\"amenity\"=\"restaurant\"",
"\"amenity\"=\"pub\""
))The vector of features contains key-value pairs
separated by an overpass
“filter” symbol such as =, !=, or
~. Each key and value must be enclosed in escape-delimited
quotations as shown above.
Full lists of available features and corresponding tags are available
in the functions ?available_features
and ?available_tags.
An overpass query constructed with the opq() and
add_osm_feature() functions is then sent to the overpass server to request data.
These data may be returned in a variety of formats, currently
including:
osmdata_xml();osmdata_sf();osmdata_sp()
(DEPRECATED);osmdata_sc();
anddata.frame format via osmdata_data_frame().Data may also be trimmed to within a defined polygonal shape with the
trim_osmdata()
function. Full package functionality is described on the website
citation ("osmdata")
#> To cite osmdata in publications use:
#>
#> Mark Padgham, Bob Rudis, Robin Lovelace, Maëlle Salmon (2017).
#> "osmdata." _Journal of Open Source Software_, *2*(14), 305.
#> doi:10.21105/joss.00305 <https://doi.org/10.21105/joss.00305>,
#> <https://joss.theoj.org/papers/10.21105/joss.00305>.
#>
#> A BibTeX entry for LaTeX users is
#>
#> @Article{,
#> title = {osmdata},
#> author = {{Mark Padgham} and {Bob Rudis} and {Robin Lovelace} and {Maëlle Salmon}},
#> journal = {Journal of Open Source Software},
#> year = {2017},
#> volume = {2},
#> number = {14},
#> pages = {305},
#> month = {jun},
#> publisher = {The Open Journal},
#> url = {https://joss.theoj.org/papers/10.21105/joss.00305},
#> doi = {10.21105/joss.00305},
#> }All data that you access using osmdata is licensed under
OpenStreetMap’s
license, the Open Database Licence. Any derived data and products
must also carry the same licence. You should make sure you understand
that licence before publishing any derived datasets.
osmextract is
an R package for downloading and importing compressed ‘extracts’ of OSM
data covering large areas (e.g. all roads in a country). The package
represents data in sf format only,
and only allows a single “layer” (such as points, lines, or polygons) to
be read at one time. It is nevertheless recommended over osmdata for
large queries of single layers, or where relationships between layers
are not important.
osmapiR is an R
interface to the OpenStreetMap API
v0.6 for fetching and saving raw geodata from/to the OpenStreetMap
database. This package allows access to OSM maps data as well as map
notes, GPS traces, changelogs, and users data. osmapiR
enables editing or exploring the history of OSM objects, and is not
intended to access OSM map data for other purposes (unlike the osmdata
or osmextract packages).
Please note that this package is released with a Contributor Code of Conduct. By contributing to this project, you agree to abide by its terms.
All contributions to this project are gratefully acknowledged using
the allcontributors
package following the allcontributors specification.
Contributions of any kind are welcome!
sckott |
nsfinkelstein |
gawbul |
edzer |
MAnalytics |
richardellison |
cboettig |
prise6 |
PaoloFrac |
Dris101 |
TomBor |
matkoniecz |
urswilke |
Robsteranium |
assignUser |
rsbivand |
