getbb
Get bounding box for a given place name
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, poly_num = c(1, 1))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), 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
- poly_num
Which of matching polygons should be used? The first polygon in the first match is the default (
c(1, 1)).
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.
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",
http://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") # only selects 1st of multipolygons
getbb("accra", format_out = "sf_polygon") # rectangular bb
# 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)
}
# }