% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/geocode_osm.R
\name{geocode_osm}
\alias{geocode_osm}
\title{Geocode addresses and coordinates with OpenStreetMap}
\usage{
geocode_osm(
  query,
  match_num = 1,
  return_all = FALSE,
  details = FALSE,
  reverse = FALSE,
  lon = NULL,
  lat = NULL,
  zoom = 10,
  user_agent = NULL
)
}
\arguments{
\item{query}{Address or place name to be geocoded. Character string. Ignored
if \code{reverse=TRUE}.}

\item{match_num}{If query matches multiple locations, which match to return?
Default is 1 (highest-ranking match, by relevance). Numeric.}

\item{return_all}{Should all matches be returned? Overrides \code{match_num}
if \code{TRUE}. Default is \code{FALSE}. Logical.}

\item{details}{Should detailed results be returned? Default is \code{FALSE}.
Logical. Ignored if \code{reverse=TRUE}.}

\item{reverse}{Should reverse geocoding be performed (coordinates to address)?
Default is \code{FALSE}. Logical.}

\item{lon}{Longitude of the point to reverse geocode. Required if
\code{reverse=TRUE}. Numeric.}

\item{lat}{Latitude of the point to reverse geocode. Required if
\code{reverse=TRUE}. Numeric.}

\item{zoom}{Zoom level for reverse geocoding, controlling the level of detail
returned (0 = country, 10 = city, 18 = building). Default is 10. Numeric.}

\item{user_agent}{Valid User-Agent identifying the application for
OSM Nominatim. If none supplied, function will attempt to auto-detect.
Character string.}
}
\value{
A \code{data.frame} object.

  For forward geocoding (\code{reverse=FALSE}):
  \itemize{
  \item \code{query}. User-supplied address query. Character string.
  \item \code{osm_id}. OpenStreetMap ID. Character string.
  \item \code{address}. OpenStreetMap address. Character string.
  \item \code{longitude}. Horizontal coordinate. Numeric.
  \item \code{latitude}. Vertical coordinate. Numeric.
  }
  If \code{details=TRUE}, also contains:
  \itemize{
  \item \code{osm_type}. OpenStreetMap feature type. Character string.
  \item \code{importance}. Relevance of Nominatim match to query, from 0
    (worst) to 1 (best). Numeric.
  \item \code{bbox_ymin}. Minimum vertical coordinate of bounding box. Numeric.
  \item \code{bbox_ymax}. Maximum vertical coordinate of bounding box. Numeric.
  \item \code{bbox_xmin}. Minimum horizontal coordinate of bounding box. Numeric.
  \item \code{bbox_xmax}. Maximum horizontal coordinate of bounding box. Numeric.
  }

  For reverse geocoding (\code{reverse=TRUE}):
  \itemize{
  \item \code{osm_name}. Full display name from OpenStreetMap. Character string.
  \item \code{osm_adm0_code}. ISO country code. Character string.
  \item \code{osm_adm0}. Country name. Character string.
  \item \code{osm_adm1}. State or first-level administrative division. Character string.
  \item \code{osm_adm2}. District or county. Character string.
  \item \code{osm_adm3}. Municipality. Character string.
  \item \code{osm_adm4}. Borough, village or street. Character string.
  }
}
\description{
Finds geographic coordinates of addresses and place names (forward geocoding),
or converts longitude/latitude coordinates to place names and administrative
units (reverse geocoding), using OpenStreetMap's Nominatim API.
}
\details{
Note that the Nominatim Usage Policy stipulates an absolute maximum
  of 1 request per second
  (\url{https://operations.osmfoundation.org/policies/nominatim/}).
  For batch geocoding of multiple addresses, please use
  \code{\link[SUNGEO]{geocode_osm_batch}}.
}
\examples{
# Geocode an address (top match only)
geocode_osm("Michigan Stadium")

# Return detailed results for top match
geocode_osm("Michigan Stadium", details = TRUE)

# Return detailed results for all matches
geocode_osm("Michigan Stadium", details = TRUE, return_all = TRUE)

# Reverse geocode a coordinate pair
geocode_osm(reverse = TRUE, lon = -83.74868, lat = 42.26587, zoom = 18)

}
