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
)

Value

Defaults to a matrix in the form: min max x ... ... y ... ...

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 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.

For format_out = "osm_type_id", a character string representing an OSM object in overpass query language. For example: "relation(id:11747082)" represents the area of the Catalan Countries. If one exact match exists with potentially multiple polygonal boundaries, only the first relation or way is returned. A set of objects can also be represented for multiple results (e.g. relation(id:11747082,307833); way(id:22422490)). See examples below for illustration. The OSM objects that can be used as areas in overpass queries

must be closed rings (ways or relations).

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 https://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), sf_polygon (for polygons that work with the sf package), polygon (full polygonal bounding boxes for each match) or osm_type_id ( string for quering inside deffined OSM areas bbox_to_string()).
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? TRUE by default

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 https://wiki.openstreetmap.org/wiki/Nominatim for details.

Examples

Run this code

if (FALSE) {
getbb ("Salzburg")
# select based on display_name, print query url
getbb ("Hereford", display_name_contains = "United States", silent = FALSE)
# top 3 matches as data frame
getbb ("Hereford", format_out = "data.frame", limit = 3)

# Examples of polygonal boundaries
bb <- getbb ("london uk", format_out = "polygon") # single match
dim (bb [[1]] [[1]]) # matrix of longitude/latitude pairs
bb_sf <- getbb ("kathmandu", format_out = "sf_polygon")
# sf:::plot.sf(bb_sf) # can be plotted if sf is installed
getbb ("london", format_out = "sf_polygon")
getbb ("accra", format_out = "sf_polygon") # rectangular bb

area <- getbb ("València", format_out = "osm_type_id")
# select multiple areas with format_out = "osm_type_id"
areas <- getbb ("València", format_out = "data.frame")
bbox_to_string (areas [areas$osm_type != "node", ])

# Using an alternative service (locationiq requires an API key)
# add LOCATIONIQ=type_your_api_key_here to .Renviron:
key <- Sys.getenv ("LOCATIONIQ")
if (nchar (key) == 32) {
    getbb (place_name,
        base_url = "https://locationiq.org/v1/search.php",
        key = key
    )
}
}