osmdata 
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).
Installation
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.2'Usage
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() 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 multipolygons
OSM data can also be downloaded in OSM XML format with osmdata_xml()
and saved for use with other software.
osmdata_xml(q1, "data.osm")Bounding Boxes
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] "matrix" "array"
head (b [[1]])
#> [1] 77.4601Features
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 theseNegation 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.
Data Formats
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:
- XML data (downloaded locally) via
osmdata_xml(); - Simple Features (sf) format
via
osmdata_sf(); - R Spatial (sp) format via
osmdata_sp(); - Silicate (SC) format via
osmdata_sc(); and data.frameformat viaosmdata_data_frame().
Additional Functionality
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
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},
#> }Data licensing
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.
Other approaches
- 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
sfformat 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.
Code of Conduct
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.
Contributors
All contributions to this project are gratefully acknowledged using the
allcontributors
package following the
all-contributors specification.
Contributions of any kind are welcome!
Code
Issue Authors
Issue Contributors
sckott |
nsfinkelstein |
gawbul |
edzer |
MAnalytics |
richardellison |
cboettig |
prise6 |
PaoloFrac |
Dris101 |
TomBor |
matkoniecz |
urswilke |
Robsteranium |
assignUser |
