Skip to contents

Get bounding box for a given place name

Source: R/getbb.R
getbb.Rd

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 = c("matrix", "data.frame", "string", "polygon", "sf_polygon",
    "osm_type_id"),
  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 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

Value

For format_out = "matrix", the default, return the bounding box:

  min   max
x ...   ...
y ...   ...

If format_out = "polygon", a list of polygons and multipolygons with one item for each nominatim result. The items are named with the OSM type and id. Each polygon is formed by one or more two-columns matrices of polygonal longitude-latitude points. The first matrix represents the outer boundary and the next ones represent holes. See examples below for illustration.

If format_out = "sf_polygon", a sf object. Each row correspond to a place_name within nominatim result.

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

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.

Note

Specific values of featuretype include "street", "city", https://wiki.openstreetmap.org/wiki/Nominatim for details). The default featuretype = "settlement" combines results from all intermediate levels below "country" and above "streets". If the bounding box or polygon of a city is desired, better results will usually be obtained with featuretype = "city".

See also

Other queries: add_osm_feature(), add_osm_features(), bbox_to_string(), opq(), opq_around(), opq_csv(), opq_enclosing(), opq_osm_id(), opq_string(), overpass_status()

Examples

if (FALSE) { # \dontrun{
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 ("Milano, Italy", format_out = "polygon")
# A polygon and a multipolygon:
str (bb) # matrices of longitude/latitude pairs

bb_sf <- getbb ("kathmandu", format_out = "sf_polygon")
bb_sf
# sf:::plot.sf(bb_sf) # can be plotted if sf is installed
getbb ("london", format_out = "sf_polygon")

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
    )
}
} # }