R: Get bounding box for a given place name

getbb {osmdata} | R Documentation

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

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

### 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"`.

### Examples

    ## Not run:
    getbb("Salzburg")
    # select based on display_name, print query url
    getbb("Hereford", display_name_contains = "USA", 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
    # 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)
    }

    ## End(Not run)

[Package osmdata version 0.1.3 Index]