% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/geo-amenity.R
\encoding{UTF-8}
\name{geo_amenity}
\alias{geo_amenity}
\title{Look up OpenStreetMap amenities}
\usage{
geo_amenity(
  bbox,
  amenity,
  lat = "lat",
  long = "lon",
  limit = 1,
  full_results = FALSE,
  return_addresses = TRUE,
  verbose = FALSE,
  nominatim_server = "https://nominatim.openstreetmap.org/",
  progressbar = TRUE,
  custom_query = list(),
  strict = FALSE
)
}
\arguments{
\item{bbox}{A numeric vector, an \code{\link[sf:st_sf]{sf}} object or an
\code{\link[sf:st_sfc]{sfc}} object specifying a bounding box (viewbox) used to
limit the search. Numeric vectors must contain \strong{longitude} (\code{x}) and
\strong{latitude} (\code{y}) in the form \verb{(xmin, ymin, xmax, ymax)}. See \strong{Details}.}

\item{amenity}{A character vector of amenities to look up,
for example \code{c("pub", "restaurant")}. See \link{osm_amenities}.}

\item{lat}{A character string specifying the name of the latitude column in
the output. Defaults to \code{"lat"}.}

\item{long}{A character string specifying the name of the longitude column
in the output. Defaults to \code{"lon"}.}

\item{limit}{A positive integer specifying the maximum number of results to
return per query. Nominatim returns at most 50 results per query.}

\item{full_results}{A logical value indicating whether to return all
available fields from the Nominatim API. If \code{FALSE}, only query metadata,
location data and requested address columns are returned.}

\item{return_addresses}{A logical value indicating whether to include
single-line addresses in the results.}

\item{verbose}{A logical value indicating whether to display detailed
messages in the console.}

\item{nominatim_server}{A character string specifying the base URL of the
Nominatim server. Defaults to
\code{"https://nominatim.openstreetmap.org/"}.}

\item{progressbar}{A logical value indicating whether to display a progress
bar when processing multiple queries.}

\item{custom_query}{A named list of additional API parameters, for example
\code{list(countrycodes = "US")}. See \strong{Details}.}

\item{strict}{A logical value indicating whether to keep only results inside
\code{bbox}. If \code{FALSE} (the default), Nominatim may return results outside the
bounding box.}
}
\value{
A \code{\link[dplyr:tibble]{tibble}} with the results that match the query.
}
\description{
Looks up OpenStreetMap \link[=osm_amenities]{amenities} within a bounding box of
the form \verb{(xmin, ymin, xmax, ymax)}. Results are returned as a
\link[dplyr:tibble]{tibble}. Use \code{\link[=geo_amenity_sf]{geo_amenity_sf()}} to return an
\code{\link[sf:st_sf]{sf}} object instead.
}
\details{
Bounding boxes can be located using online tools such as
\url{https://boundingbox.klokantech.com/}.

For a full list of valid amenities, see
\url{https://wiki.openstreetmap.org/wiki/Key:amenity} and \link{osm_amenities}.

See \url{https://nominatim.org/release-docs/latest/api/Search/} for additional
parameters to pass to \code{custom_query}.
}
\examples{
\dontshow{if (nominatim_check_access()) withAutoprint(\{ # examplesIf}
\donttest{
# Define a bounding box around Times Square, New York.
bbox <- c(
  -73.9894467311, 40.75573629,
  -73.9830630737, 40.75789245
)

geo_amenity(
  bbox = bbox,
  amenity = "restaurant"
)

# Search for multiple amenities.
geo_amenity(
  bbox = bbox,
  amenity = c("restaurant", "pub")
)

# Increase `limit` and use strict filtering.
geo_amenity(
  bbox = bbox,
  amenity = c("restaurant", "pub"),
  limit = 10,
  strict = TRUE
)
}
\dontshow{\}) # examplesIf}
}
\seealso{
\code{\link[=bbox_to_poly]{bbox_to_poly()}} for converting bounding box coordinates to a
\CRANpkg{sf} polygon.

Amenity lookup functions and data:
\code{\link[=geo_amenity_sf]{geo_amenity_sf()}},
\code{\link{osm_amenities}}
}
\concept{amenity}
