“Using R to Access OpenStreetMap (OSM) Data”

OpenStreetMap is a collaborative and freely available geographic data set that serves as a global map of the world’s features. It is, therefore, an enormous data set, and downloading some desired subset of the data for manipulation, mapping, and analysis can be something of a challenge for the uninitiated. Thankfully, the R programming language and its associated integrated development environment (IDE), RStudio, can make obtaining OSM vector data a relatively seamless and pain-free process with the use of the osmdata package.

Installing osmdata in RStudio

Assuming R and RStudio are installed on your system, you will first need to get the osmdata package installed in your R library. In R, packages are collections of functions, data, and documentation that extend the capabilities of the base R language.

RStudio allows users to create and work with many different file types. R Markdown (.rmd) files are a powerful and versatile file type that allow for the combination of code, text, and output in a single file. Create a new .rmd file to get started.

Text and code can coexist in a Markdown document because code is set apart from text through the creation of code blocks, or ‘chunks’. A code chunk is the space in which R code can be written and executed. To initiate a code chunk in Markdown, type three backticks followed by a lowercase ‘r’ between curly brackets. To close a code chunk, type three more backticks below the last line of code:

To install the osmdata package in your R library, create a code chunk (be sure to include the opening AND closing sets of backticks. Without the closing backticks the code will not run) and execute the following code:

install.packages("osmdata")

Once the package is successfully installed, load it for use by using the library() function and passing the package name to it.

library(osmdata)

It is perfectly fine for both of these lines of code to be executed inside the same chunk. Using multiple chunks can be advantageous if your R code becomes longer and more involved. For instance, once you start digging into the OSM data it might make sense to create distinct chunks to logically separate different parts of the wrangling/analysis. It can also make it easier to identify where an error is originating when the code is broken into digestible blocks.

Querying the OpenStreetMap Database

The overpass API

osmdata uses the overpass API for accessing and querying data from the OpenStreetMap database. overpass queries are initiated by calling the function opq(). All overpass queries must begin by specifying a bounding box that defines the spatial extent of the area to be queried. The bounding box parameter is specified with the argument bbox=, and can be indicated by regular character strings enclosed in single quotation marks:

# Any query within Newport News would begin like this. The results of the query are here assigned to a variable named `query_output`.

  query_output <- opq(bbox = 'Newport News, VA')

Note: The output of any function call can be stored in a variable using the <- operator. query_output is an intuitive name for the variable holding the output from an opq() function call, but realize that you can name the variable anything you want.

Constructing Queries

Key/value pairs

Features in OpenStreetMap are identified by a key/value pair. There are over two dozen feature keys, and many dozens more values corresponding to those keys. The best resource available for finding the appropriate key/value pair for the feature(s) you are interested in is the OpenStreetMap Map Features wiki.

OpenStreetMap Map Features Wiki

Let’s suppose you want to pull data from OSM corresponding to restaurants, bars, amenities, leisure, gyms, shopping, and supermarkets. Some of these categories are treated as ‘keys’ within the OSM database, while others constitute ‘values.’ It is therefore essential to refer to the Map Features wiki and sort of out which is which.

Depending on how your query is constructed, it is possible to either select a subset of the features that fall under a given key or simply select for all values corresponding to a given key by leaving out the value= parameter. Amenities and leisure, for instance, are enormous categories comprising dozens of different features. Likewise, OSM includes an extensive range of highly specific shop-types, and so it will depend on the nature of your analysis whether or not it is advisable to include every feature that corresponds to a particular key in your query output.

For this example we will query a subset of ‘amenity’ and ‘shop’ values and select for all ‘leisure’ values. (Note that ‘gym’ is a value tied to the ‘leisure’ key, and so is not specified in the table below.)

POI	Key	Value
restaurants	'amenity'	'restaurant'
bars	'amenity'	'bar'
cinemas	'amenity'	'cinema'
nightclubs	'amenity'	'nightclub'
(all leisure)	'leisure'	NA
supermarket	'shop'	'supermarket'
clothing store	'shop'	'clothes'

add_osm_features()

To extract these features from the OSM database you will build upon the initial opq() query above by specifying the features you want within the function add_osm_features(). This query gets linked to the original opq() function through the use of %>%, the ‘pipe’ operator.

# This query will return all features tagged as restaurants within the Newport News bounding box. Note use of 'pipe' operator, `%>%`. This is essential for the query to execute correctly.

  query_output <- opq(bbox = 'Newport News, VA') %>%  
    add_osm_feature(key = 'amenity', value = 'restaurant')

Next, append the osmdata_sf() function, again linked using the %>% operator, to convert the OSM data to a spatial data object. This step is necessary to eventually be able to export the query results for use in a GIS. It is not necessary to include an argument in the parentheses. By using the %>% operator, it is implicitly understood that the query output should be taken as the input in osmdata_sf().

  query_output <- opq(bbox = 'Newport News, VA') %>%
    add_osm_feature(key = 'amenity', value = 'restaurant') %>%
    osmdata_sf()

print(query_output)

## Object of class 'osmdata' with:
##                  $bbox : 36.8175016,-76.58977,37.1375016,-76.26977
##         $overpass_call : The call submitted to the overpass API
##                  $meta : metadata including timestamp and version numbers
##            $osm_points : 'sf' Simple Features Collection with 2004 points
##             $osm_lines : NULL
##          $osm_polygons : 'sf' Simple Features Collection with 171 polygons
##        $osm_multilines : NULL
##     $osm_multipolygons : NULL

You can see that this query has returned a spatial data object with 1963 points and 164 polygon features.

Further Developing Queries

‘AND’ queries

Any subsequent call to add_osm_feature() will add a new feature to the query. Combining feature queries in this way is equivalent to using the ‘AND’ operator. For example, the following query will return all features that are BOTH restaurants AND bars.

# Adding an additional feature query corresponds to the logical AND operator. This query will return features that are both restaurants AND bars.

  restaurantsWithBars <- opq(bbox = 'Newport News, VA') %>%
    add_osm_feature(key = 'amenity', value = 'restaurant') %>%
    add_osm_feature(key = 'amenity', value = 'bar') %>%
    osmdata_sf()

print(restaurantsWithBars)

## Object of class 'osmdata' with:
##                  $bbox : 36.8175016,-76.58977,37.1375016,-76.26977
##         $overpass_call : The call submitted to the overpass API
##                  $meta : metadata including timestamp and version numbers
##            $osm_points : 'sf' Simple Features Collection with 28 points
##             $osm_lines : NULL
##          $osm_polygons : 'sf' Simple Features Collection with 0 polygons
##        $osm_multilines : NULL
##     $osm_multipolygons : NULL

The spatial data object contained in the variable restaurantsWithBars contains only 28 points and 0 polygons. The number of features returned is far lower now that a second condition (‘AND ’bars’’) has been added to the query.

‘OR’ queries

What if you want to query features that are either a restaurant OR a bar? In this case, you would need to take one of two approaches to constructing the query.

1. You can query each feature separately. In this case, each query result should be stored in its own variable and each set of features will end up being exported as its own file.

rests <- opq(bbox = 'Newport News, VA') %>%
  add_osm_feature(key = 'amenity', value = 'restaurant') %>%
  osmdata_sf()


bars <- opq(bbox = 'Newport News, VA') %>%
  add_osm_feature(key = 'amenity', value = 'bar') %>%
  osmdata_sf()


cinemas <- opq(bbox = 'Newport News, VA') %>%
  add_osm_feature(key = 'amenity', value = 'cinema') %>%
  osmdata_sf()


nightclubs <- opq(bbox = 'Newport News, VA') %>%
  add_osm_feature(key = 'amenity', value = 'nightclub') %>%
  osmdata_sf()


supers <- opq(bbox = 'Newport News, VA') %>%
  add_osm_feature(key = 'shop', value = 'supermarket') %>%
  osmdata_sf()


clothes <- opq(bbox = 'Newport News, VA') %>%
  add_osm_feature(key = 'shop', value = 'clothes') %>%
  osmdata_sf()


all_leisure <- opq(bbox = 'Newport News, VA') %>%
  add_osm_feature(key = 'leisure') %>%
  osmdata_sf()

Note that it is possible to combine any values from the same key (e.g., ‘restaurant’ and ‘bar’ are both values to the ‘amenity’ key) into a single query by using the c() function to construct a vector of names corresponding to the desired keys. Thus, the sequence of queries in the chunk above can be modified to look like:

amenity_ftrs <- opq(bbox = 'Newport News, VA') %>%
  add_osm_feature(key = 'amenity', value = c('restaurant', 'bar', 'cinema')) %>%
  osmdata_sf()


shop_ftrs <- opq(bbox = 'Newport News, VA') %>%
  add_osm_feature(key = 'shop', value = c('supermarket', 'clothes')) %>%
  osmdata_sf()


all_leisure <- opq(bbox = 'Newport News, VA') %>%
  add_osm_feature(key = 'leisure') %>%
  osmdata_sf()

The crucial difference is in how the data will be exported. With the first set of queries, you will end up with seven separate data layers, one for each feature (except for all_leisure, which contains all features corresponding to the ‘leisure’ key). With the second query structure, you will have only three different data layers, and whichever features are grouped within the c() function will be output together in a single layer.

2. Alternatively, you can combine the feature queries in a single call to add_osm_feature() using the ‘OR’ syntax, shown below. This will return all features that are a restaurant OR a bar OR a cinema, etc. This approach entails the export of one single layer containing all the features enumerated in the query.

# Note that when using the 'OR' syntax the 'key=' and 'value=' parameters are not explicitly stated. Instead, backslaches and quotation marks are used in a less-than intuitive way.

all_features_in_one_query <- opq(bbox = 'Newport News, VA') %>%
  add_osm_features(features = c("\"amenity\"=\"restaurant\"",
                                "\"amenity\"=\"bar\"",
                                "\"amenity\"=\"cinema\"",
                                "\"amenity\"=\"nightclub\"",
                                "\"shop\"=\"supermarket\"",
                                "\"shop\"=\"clothes\"",
                                "\"leisure\"")) %>%  
  osmdata_sf()

Additional tags

Most feature queries can be further refined through the use of additional tags. For instance, if you were looking for bars that feature live music, you could add the tag live_music=yes within the add_osm_feature() function call for bars. The tags that can be used in combination with keys and values can be found by exploring the Map Features wiki and clicking on the key or value you are interested in.

Exporting for Use in ArcGIS

By chaining osmdata_sf() to the end of your queries, the query output is converted into a spatial data object. The last step is to export that spatial data object in a way that can be incorporated into a GIS outside of the R environment. The sf package provides a powerful set of tools for working with spatial data, including the function st_wite() which be used to export the osmdata object as something that can be brought into ArcGIS Pro.

First, install and load the sf package:

install.packages("sf")
library(sf)

Depending on your query, the resulting osmdata_sf() output could contain points, lines, polygons, multilines, or multipolygons. The st_write() function can only write one type of geometric feature at a time. You must specify the geometry by appending $osm_ and the name of the desired feature to your output variable name. For instance, to specify ‘points’, you would use query_output$osm_points. If you want the polygons contained in the output, you would use query_output$osm_polygons.

To export…	…add to the end of your query variable
points	$osm_points
lines	$osm_lines
polygons	$osm_polygons
multilines	osm_multilines
multipolygons	osm_multipolygons

Pass the desired geometry to the st_write() function and specify the file name and the path where it should be written. st_write() can output a variety of file types, including both shapefile and GeoJSON. Exporting as .shp often results in corrupted files. The best approach is to export as .geojson, and convert the resulting file to a feature class using the ‘JSON to Features’ tool in ArcGIS Pro.

# First pass the variable with geometry specified, then indicate the desired file path in double quotation marks.

st_write(query_output$osm_points, "N:/Workspace/acameron/OSMdata/restaurant_points.geojson")

Note that the resulting point layer contains all the features within the Newport News bounding box, not just within the Newport News boundary polygon.

---

This tutorial is adapted from the CRAN vignette for osmdata, available here. Please consult the linked documentation for a more detailed look at how to use the osmdata package.