osmextract: oe_get – R documentation

Become an expert in R — Interactive courses, Cheat Sheets, certificates and more!

oe_get

Find, download, translate and read OSM extracts from several providers

Description

This function is used to find, download, translate and read OSM extracts obtained from several providers. It is a wrapper around oe_match() and oe_read(). Check the introductory vignette, the examples and the help pages of the wrapped functions to understand the details behind all parameters.

Usage

oe_get(
  place,
  layer = "lines",
  ...,
  provider = "geofabrik",
  match_by = "name",
  max_string_dist = 1,
  level = NULL,
  download_directory = oe_download_directory(),
  force_download = FALSE,
  max_file_size = 5e+08,
  vectortranslate_options = NULL,
  osmconf_ini = NULL,
  extra_tags = NULL,
  force_vectortranslate = FALSE,
  download_only = FALSE,
  skip_vectortranslate = FALSE,
  never_skip_vectortranslate = FALSE,
  quiet = FALSE
)

Arguments

`place`	Description of the geographical area that should be matched with a `.osm.pbf` file through the chosen `provider`. Can be either a length-1 character vector, an `sf` or `sfc` object, or a numeric vector of coordinates with length 2. In the last case, it is assumed that the EPSG code is 4326 specified as c(LON, LAT), while you can use any CRS with an `sf` or `sfc` object. See Details and examples in `oe_match()`.
`layer`	Which `layer` should be read in? Typically `points`, `lines` (the default), `multilinestrings`, `multipolygons` or `other_relations`. If you specify an ad-hoc query using the argument `query` (see introductory vignette and examples), then `oe_get()` and `oe_read()` will read the layer specified in the query and ignore `layer`. See also #122.
`...`	Arguments that will be passed to `sf::st_read()`, like `query`, `wkt_filter` or `stringsAsFactors`. Check the introductory vignette to understand how to create your own (SQL-like) queries.
`provider`	Which provider should be used to download the data? Available providers can be found with the following command: `oe_providers()`. For `oe_get()` and `oe_match()`, if `place` is equal to `ITS Leeds`, then `provider` is set equal to `test`. This is just for simple examples and internal tests.
`match_by`	Which column of the provider's database should be used for matching the input `place` with a `.osm.pbf` file? The default is `"name"`. Check Details and Examples in `oe_match()` to understand how this parameter works. Ignored if `place` is not a character vector since the matching is performed through a spatial operation.
`max_string_dist`	Numerical value greater or equal than 0. What is the maximum distance in fuzzy matching (i.e. Approximate String Distance, see `adist()`) between input `place` and `match_by` column to tolerate before testing alternative providers or looking for geographical matching with Nominatim API? This parameter is set equal to 0 if `match_by` is equal to `iso3166_1_alpha2` or `iso3166_2`. Check Details and Examples in `oe_match()` to understand why this parameter is important. Ignored if `place` is not a character vector since the matching is performed through a spatial operation.
`level`	An integer representing the desired hierarchical level in case of spatial matching. For the `geofabrik` provider, for example, `1` corresponds with continent-level datasets, `2` for countries, `3` corresponds to regions and `4` to subregions. Hence, we could approximately say that smaller administrative units correspond to bigger levels. If `NULL`, the default, the `oe_*` functions will select the highest available level. See Details and Examples in `oe_match()`.
`download_directory`	Where to download the file containing the OSM data? By default this is equal to `oe_download_directory()`, which is equal to `tempdir()` and it changes each time you restart R. You can set a persistent `download_directory` by adding the following to your `.Renviron` file (e.g. with `edit_r_environ` function in `usethis` package): `OSMEXT_DOWNLOAD_DIRECTORY=/path/to/osm/data`.
`force_download`	Should the `.osm.pbf` file be updated if it has already been downloaded? `FALSE` by default. This parameter is used to update old `.osm.pbf` files.
`max_file_size`	The maximum file size to download without asking in interactive mode. Default: `5e+8`, half a gigabyte.
`vectortranslate_options`	Options passed to the `sf::gdal_utils()` argument `options`. Set by default. Check details in the introductory vignette and the help page of `oe_vectortranslate()`.
`osmconf_ini`	The configuration file. See documentation at gdal.org. Check details in the introductory vignette and the help page of `oe_vectortranslate()`. Set by default.
`extra_tags`	Which additional columns, corresponding to OSM tags, should be in the resulting dataset? `NULL` by default. Check the introductory vignette and the help pages of `oe_vectortranslate()` and `oe_get_keys()`. Ignored when `osmconf_ini` is not `NULL`.
`force_vectortranslate`	Boolean. Force the original `.pbf` file to be translated into a `.gpkg` file, even if a `.gpkg` with the same name already exists? `FALSE` by default. If tags in `extra_tags` match data in previously translated `.gpkg` files no translation occurs (see #173 for details). Check the introductory vignette and the help page of `oe_vectortranslate()`.
`download_only`	Boolean. If `TRUE`, then the function only returns the path where the matched file is stored, instead of reading it. `FALSE` by default.
`skip_vectortranslate`	Boolean. If `TRUE`, then the function skips all vectortranslate operations and it reads (or simply returns the path) of the `.osm.pbf` file. `FALSE` by default.
`never_skip_vectortranslate`	Boolean. This is used in case the user passed its own `.ini` file or vectortranslate options (since, in those case, it's too difficult to determine if an existing `.gpkg` file was generated following the same options.)
`quiet`	Boolean. If `FALSE`, the function prints informative messages. Starting from `sf` version 0.9.6, if `quiet` is equal to `FALSE`, then vectortranslate operations will display a progress bar.

Details

The algorithm that we use for importing an OSM extract data into R is divided into 4 steps: 1) match the input place with the url of a .pbf file; 2) download the .pbf file; 3) convert it into .gpkg format and 4) read-in the .gpkg file. The function oe_match() is used to perform the first operation and the function oe_read() (which is a wrapper around oe_download(), oe_vectortranslate() and sf::st_read()) performs the other three operations.

Value

An sf object.

Examples

# Download OSM extracts associated to a simple test.
its = oe_get("ITS Leeds", quiet = FALSE)
class(its)
unique(sf::st_geometry_type(its))

# Get another layer from the test extract
its_points = oe_get("ITS Leeds", layer = "points")
unique(sf::st_geometry_type(its_points))

# Get the .osm.pbf and .gpkg file path
oe_get("ITS Leeds", download_only = TRUE)
oe_get("ITS Leeds", download_only = TRUE, skip_vectortranslate = TRUE)
# See also ?oe_find()

# Add additional tags
its_with_oneway = oe_get("ITS Leeds", extra_tags = "oneway", quiet = FALSE)
names(its_with_oneway)
table(its_with_oneway$oneway, useNA = "ifany")

# Use the query argument to get only oneway streets:
q = "SELECT * FROM 'lines' WHERE oneway IN ('yes')"
its_oneway = oe_get("ITS Leeds", query = q)
its_oneway

## Not run: 
# A more complex example
west_yorkshire = oe_get("West Yorkshire", quiet = FALSE)
# If you run it again, the function will not download the file
# or convert it again
west_yorkshire = oe_get("West Yorkshire", quiet = FALSE)
# Match with place name
oe_get("Milan") # Warning: the .pbf file is 400MB
oe_get("Vatican City")
oe_get("Zurich")

# Match with coordinates (any EPSG)
milan_duomo = sf::st_sfc(sf::st_point(c(1514924, 5034552)), crs = 3003)
oe_get(milan_duomo, quiet = FALSE) # Warning: the .pbf file is 400MB
# Match with numeric coordinates (EPSG = 4326)
oe_match(c(9.1916, 45.4650), quiet = FALSE)
# Alternative providers
baku = oe_get(place = "Baku", provider = "bbbike", quiet = FALSE)

# Other examples:
oe_get("RU", match_by = "iso3166_1_alpha2", quiet = FALSE)
# The following example mimics read_sf
oe_get("Andora", stringsAsFactors = FALSE, quiet = TRUE, as_tibble = TRUE)
## End(Not run)

osmextract

Download and Read OpenStreetMap Data Extracts

v0.2.1

GPL-3

Authors

Andrea Gilardi [aut, cre] (<https://orcid.org/0000-0002-9424-7439>), Robin Lovelace [aut] (<https://orcid.org/0000-0001-5679-6536>), Barry Rowlingson [ctb] (<https://orcid.org/0000-0002-8586-6625>), Salva Fernández [rev] (Salva reviewed the package (v. 0.1) for rOpenSci, see <https://github.com/ropensci/software-review/issues/395>), Nicholas Potter [rev] (Nicholas reviewed the package (v. 0.1) for rOpenSci, see <https://github.com/ropensci/software-review/issues/395>)

Initial release