osmdata (version 0.0.5)

getbb: Get bounding box for a given place name

Description

This function uses the free Nominatim API provided by OpenStreetMap to find the bounding box (bb) associated with place names.

Usage

getbb(place_name, display_name_contains = NULL, viewbox = NULL,
  format_out = "matrix", base_url = "https://nominatim.openstreetmap.org",
  featuretype = "settlement", limit = 10, key = NULL, silent = TRUE)

Arguments

place_name

The name of the place you're searching for

display_name_contains

Text string to match with display_name field returned by http://wiki.openstreetmap.org/wiki/Nominatim

viewbox

The bounds in which you're searching

format_out

Character string indicating output format: matrix (default), string (see bbox_to_string), data.frame (all 'hits' returned by Nominatim), or polygon (full polygonal bounding boxes for each match).

base_url

Base website from where data is queried

featuretype

The type of OSM feature (settlement is default; see Note)

limit

How many results should the API return?

key

The API key to use for services that require it

silent

Should the API be printed to screen? FALSE by default

Value

Unless format_out = "polygon", a numeric bounding box as min and max of latitude and longitude. If format_out = "polygon", one or more two-columns matrices of polygonal longitude-latitude points. Where multiple place_name occurrences are found within nominatim, each item of the list of coordinates may itself contain multiple coordinate matrices where multiple exact matches exist. If one one exact match exists with potentially multiple polygonal boundaries (for example, "london uk" is an exact match, but can mean either greater London or the City of London), only the first is returned. See examples below for illustration.

Details

It was inspired by the functions bbox from the sp package, bb from the tmaptools package and bb_lookup from the github package nominatim package, which can be found at https://github.com/hrbrmstr/nominatim.

See http://wiki.openstreetmap.org/wiki/Nominatim for details.

Examples

# NOT RUN {
getbb("Salzburg")
place_name <- "Hereford"
getbb(place_name, silent = FALSE)
# return bb whose display_name contain text string "United States"
getbb(place_name, display_name_contains = "United States", silent = FALSE)
# top 3 matches as data frame
getbb(place_name, format_out = "data.frame", limit = 3)
# Examples of polygonal boundaries
bb <- getbb ("london uk", format_out = "polygon") # single match
dim(bb) # matrix of longitude/latitude pairs
plot(bb)
# Multiple matches return a nested list of matrices:
bb <- getbb ("london", format_out = "polygon")
sapply(bb, length) # 5 lists returned
bbmat = matrix(unlist(bb), ncol = 2)
plot(bbmat) # worldwide coverage of places called "london"
# Using an alternative service (locationiq requires an API key)
key <- Sys.getenv("LOCATIONIQ") # add LOCATIONIQ=type_your_api_key_here to .Renviron
if(nchar(key) ==  32) {
  getbb(place_name, base_url = "http://locationiq.org/v1/search.php", key = key)
}
# }