% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/reverse-geo-lite-sf.R
\encoding{UTF-8}
\name{reverse_geo_lite_sf}
\alias{reverse_geo_lite_sf}
\title{Reverse geocode coordinates and return \CRANpkg{sf} objects}
\usage{
reverse_geo_lite_sf(
  lat,
  long,
  address = "address",
  full_results = FALSE,
  return_coords = TRUE,
  verbose = FALSE,
  nominatim_server = "https://nominatim.openstreetmap.org/",
  progressbar = TRUE,
  custom_query = list(),
  points_only = TRUE
)
}
\arguments{
\item{lat}{A numeric vector of latitude values in the range
\eqn{\left[-90, 90 \right]}.}

\item{long}{A numeric vector of longitude values in the range
\eqn{\left[-180, 180 \right]}.}

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

\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_coords}{A logical value indicating whether to return the input
coordinates with 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 API-specific parameters, for example
\code{list(zoom = 3)}. 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{
Reverse geocodes latitude and longitude coordinates and returns matching
results as an \code{\link[sf:st_sf]{sf}} object. Latitude values must be in
\eqn{\left[-90, 90 \right]} and longitude values in
\eqn{\left[-180, 180 \right]}. Use \code{\link[=reverse_geo_lite]{reverse_geo_lite()}} to return a
\link[dplyr:tibble]{tibble} instead.
}
\details{
See \url{https://nominatim.org/release-docs/latest/api/Reverse/} for additional
parameters to pass to \code{custom_query}.
}
\section{About zooming}{


Set \code{custom_query = list(zoom = 3)} to adjust the output. Selected zoom
levels correspond to these address details:\tabular{ll}{
   \strong{zoom} \tab \strong{address_detail} \cr
   \code{3} \tab country \cr
   \code{5} \tab state \cr
   \code{8} \tab county \cr
   \code{10} \tab city \cr
   \code{14} \tab suburb \cr
   \code{16} \tab major streets \cr
   \code{17} \tab major and minor streets \cr
   \code{18} \tab building \cr
}
}

\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{
library(ggplot2)

# Define the Colosseum coordinates.
col_lon <- 12.49309
col_lat <- 41.89026

# Return the Colosseum as a polygon.
col_sf <- reverse_geo_lite_sf(
  lat = col_lat,
  long = col_lon,
  points_only = FALSE
)

dplyr::glimpse(col_sf)

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

# Return the city of Rome by using the same coordinates with zoom 10.

rome_sf <- reverse_geo_lite_sf(
  lat = col_lat,
  long = col_lon,
  custom_query = list(zoom = 10),
  points_only = FALSE
)

dplyr::glimpse(rome_sf)

if (!all(sf::st_is_empty(rome_sf))) {
  ggplot(rome_sf) +
    geom_sf()
}
}
\dontshow{\}) # examplesIf}
}
\seealso{
Reverse geocoding functions:
\code{\link[=reverse_geo_lite]{reverse_geo_lite()}}

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_sf]{geo_lite_sf()}},
\code{\link[=geo_lite_struct_sf]{geo_lite_struct_sf()}}
}
\concept{reverse}
\concept{spatial}
