% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/geo-amenity-sf.R
\encoding{UTF-8}
\name{geo_amenity_sf}
\alias{geo_amenity_sf}
\title{Look up OpenStreetMap amenities and return \CRANpkg{sf} objects}
\usage{
geo_amenity_sf(
  bbox,
  amenity,
  limit = 1,
  full_results = FALSE,
  return_addresses = TRUE,
  verbose = FALSE,
  nominatim_server = "https://nominatim.openstreetmap.org/",
  progressbar = TRUE,
  custom_query = list(),
  strict = FALSE,
  points_only = TRUE
)
}
\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{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,
geometry 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.}

\item{points_only}{A logical value indicating whether to return only point
geometries. If \code{FALSE}, the API may return other geometry types. See
\strong{About geometry types}.}
}
\value{
An \code{\link[sf:st_sf]{sf}} object 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 an
\code{\link[sf:st_sf]{sf}} object. Use \code{\link[=geo_amenity]{geo_amenity()}} to return a
\link[dplyr:tibble]{tibble} 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}.
}
\section{About geometry types}{


The \code{points_only} argument controls whether the results contain only points.
All Nominatim results have at least a point geometry.

When \code{points_only = FALSE}, the geometry type depends on the matching
feature. Administrative areas and major buildings are returned as polygons,
rivers and roads are returned as lines and amenities may still be returned
as points.

This function is vectorized, allowing multiple addresses to be searched.
With \code{points_only = FALSE}, multiple geometry types may be returned.
}

\examples{
\dontshow{if (nominatim_check_access()) withAutoprint(\{ # examplesIf}
\donttest{
# Retrieve the Usera district in Madrid.

library(ggplot2)
mad <- geo_lite_sf("Usera, Madrid, Spain", points_only = FALSE)

# Search for restaurants, pubs and schools.

rest_pub <- geo_amenity_sf(mad, c("restaurant", "pub", "school"),
  limit = 50
)

if (!all(sf::st_is_empty(rest_pub))) {
  ggplot(mad) +
    geom_sf() +
    geom_sf(data = rest_pub, aes(color = query, shape = query))
}
}
\dontshow{\}) # examplesIf}
}
\seealso{
Amenity lookup functions and data:
\code{\link[=geo_amenity]{geo_amenity()}},
\code{\link{osm_amenities}}

Spatial helper and output functions:
\code{\link[=bbox_to_poly]{bbox_to_poly()}},
\code{\link[=geo_address_lookup_sf]{geo_address_lookup_sf()}},
\code{\link[=geo_lite_sf]{geo_lite_sf()}},
\code{\link[=geo_lite_struct_sf]{geo_lite_struct_sf()}},
\code{\link[=reverse_geo_lite_sf]{reverse_geo_lite_sf()}}
}
\concept{amenity}
\concept{spatial}
