% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/geo-address-lookup-sf.R
\encoding{UTF-8}
\name{geo_address_lookup_sf}
\alias{geo_address_lookup_sf}
\title{Look up OpenStreetMap objects and return \CRANpkg{sf} objects}
\usage{
geo_address_lookup_sf(
  osm_ids,
  type = c("N", "W", "R"),
  full_results = FALSE,
  return_addresses = TRUE,
  verbose = FALSE,
  nominatim_server = "https://nominatim.openstreetmap.org/",
  custom_query = list(),
  points_only = TRUE
)
}
\arguments{
\item{osm_ids}{A numeric vector of OSM identifiers, for example
\code{c(12345, 67890)}.}

\item{type}{A character vector containing the OSM object type associated
with each value in \code{osm_ids}. Possible values are node (\code{"N"}), way
(\code{"W"}) and relation (\code{"R"}). A single value is recycled.}

\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{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{
Looks up addresses and other details for one or more OpenStreetMap (OSM)
objects, such as nodes, ways or relations. Results are returned as an
\code{\link[sf:st_sf]{sf}} object. Use \code{\link[=geo_address_lookup]{geo_address_lookup()}} to return a
\link[dplyr:tibble]{tibble} instead.
}
\details{
See \url{https://nominatim.org/release-docs/latest/api/Lookup/} 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{
# Look up Notre-Dame Cathedral in Paris.

NotreDame <- geo_address_lookup_sf(osm_ids = 201611261, type = "W")

# Require at least one non-empty object.
if (!all(sf::st_is_empty(NotreDame))) {
  library(ggplot2)

  ggplot(NotreDame) +
    geom_sf()
}

NotreDame_poly <- geo_address_lookup_sf(201611261,
  type = "W",
  points_only = FALSE
)

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

# Look up multiple OSM objects.

several <- geo_address_lookup_sf(c(146656, 240109189), type = c("R", "N"))
several
}
\dontshow{\}) # examplesIf}
}
\seealso{
Address lookup functions:
\code{\link[=geo_address_lookup]{geo_address_lookup()}}

Spatial helper and output functions:
\code{\link[=bbox_to_poly]{bbox_to_poly()}},
\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()}},
\code{\link[=reverse_geo_lite_sf]{reverse_geo_lite_sf()}}
}
\concept{lookup}
\concept{spatial}
