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 geofabrik for an approach for reading-in bulk OSM data extracts).


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,

OSM data can also be downloaded in OSM XML format with osmdata_xml() and saved for use with other software.

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.

The next step is to convert that to an overpass query object with the opq() function:

It is also possible to use bounding polygons rather than rectangular boxes:


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:

(Logical OR combinations are demonstrated below.) 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:

Additional arguments allow for more refined matching, such as the following request for all pubs with “irish” in the name:

See ?available_features and ?available_tags for further information.

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:

  1. XML data (downloaded locally) via osmdata_xml();
  2. Simple Features (sf) format via osmdata_sf();
  3. R Spatial (sp) format via osmdata_sp(); and
  4. Silicate (SC) format via osmdata_sc().

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.

Code of Conduct

Please note that this project is released with a Contributor Code of Conduct. By participating in this project you agree to abide by its terms.