% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/geo-lite-sf.R
\encoding{UTF-8}
\name{geo_lite_sf}
\alias{geo_lite_sf}
\title{Search for addresses with free-form queries and return \CRANpkg{sf} objects}
\usage{
geo_lite_sf(
  address,
  limit = 1,
  return_addresses = TRUE,
  full_results = FALSE,
  verbose = FALSE,
  progressbar = TRUE,
  nominatim_server = "https://nominatim.openstreetmap.org/",
  custom_query = list(),
  points_only = TRUE
)
}
\arguments{
\item{address}{A character vector of single-line addresses, for example
\code{"1600 Pennsylvania Ave NW, Washington"} or
\code{c("Madrid", "Barcelona")}.}

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

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

\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{verbose}{A logical value indicating whether to display detailed
messages in the console.}

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

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

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

\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{
Searches for addresses supplied as a character vector and returns matching
results as an \code{\link[sf:st_sf]{sf}} object. Use \code{\link[=geo_lite]{geo_lite()}} to return a
\link[dplyr:tibble]{tibble} instead.

This function performs the \strong{free-form address search} described in the
\href{https://nominatim.org/release-docs/latest/api/Search/}{API endpoint}.
}
\details{
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{
# Return point geometries.
library(ggplot2)

string <- "Statue of Liberty, NY, USA"
sol <- geo_lite_sf(string)

if (!all(sf::st_is_empty(sol))) {
  ggplot(sol) +
    geom_sf()
}

sol_poly <- geo_lite_sf(string, points_only = FALSE)

if (!all(sf::st_is_empty(sol_poly))) {
  ggplot(sol_poly) +
    geom_sf() +
    geom_sf(data = sol, color = "red")
}
# Return multiple matches.

madrid <- geo_lite_sf("Comunidad de Madrid, Spain",
  limit = 2,
  points_only = FALSE, full_results = TRUE
)

if (!all(sf::st_is_empty(madrid))) {
  ggplot(madrid) +
    geom_sf(fill = NA)
}
}
\dontshow{\}) # examplesIf}
}
\seealso{
Address search functions:
\code{\link[=geo_lite]{geo_lite()}},
\code{\link[=geo_lite_struct]{geo_lite_struct()}},
\code{\link[=geo_lite_struct_sf]{geo_lite_struct_sf()}}

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_amenity_sf]{geo_amenity_sf()}},
\code{\link[=geo_lite_struct_sf]{geo_lite_struct_sf()}},
\code{\link[=reverse_geo_lite_sf]{reverse_geo_lite_sf()}}
}
\concept{geocoding}
\concept{spatial}
