---
title: "Get started with nominatimlite"
description: Search for addresses and work with Nominatim API results.
vignette: >
  %\VignetteIndexEntry{Get started with nominatimlite}
  %\VignetteEngine{quarto::html}
  %\VignetteEncoding{UTF-8}
bibliography: REFERENCES.bib
link-citations: true
tbl-cap-location: bottom
---

<!-- nominatimlite.qmd is generated from nominatimlite.qmd.orig. Please edit that file -->



**nominatimlite** provides a lightweight interface to the [**Nominatim
API**](https://nominatim.org/release-docs/latest/). It supports free-form and
structured address searches, reverse geocoding, amenity lookup and address
lookup by **OpenStreetMap** (OSM) object identifier. Results are returned as
tibbles or **sf** objects.

The full site with examples and vignettes is available at
<https://dieghernan.github.io/nominatimlite/>.

## What is Nominatim?

**Nominatim** searches [**OpenStreetMap**](https://www.openstreetmap.org/) data by
name and address
([geocoding](https://wiki.openstreetmap.org/wiki/Geocoding "Geocoding")) and
reverse geocodes geographic coordinates.

## Why nominatimlite?

**nominatimlite** accesses the **Nominatim API** without requiring the
**curl** package. This makes the package useful in environments where
**curl** is not available. API requests use base **R** functions instead.

## Recommended packages

Related packages provide broader interfaces to geocoding services and
**OpenStreetMap** data:

- [**tidygeocoder**](https://jessecambon.github.io/tidygeocoder/)
  [@R-tidygeocoder] provides an interface to geocoding services such as
  **Nominatim**, **Google**, **TomTom** and **Mapbox**.
- [**osmdata**](https://docs.ropensci.org/osmdata/) [@R-osmdata] downloads
  spatial data from **OpenStreetMap** with the [**Overpass**
  API](https://wiki.openstreetmap.org/wiki/Overpass_API).
- [**arcgeocoder**](https://dieghernan.github.io/arcgeocoder/) [@R-arcgeocoder]
  provides a lightweight interface for geocoding with the **ArcGIS REST API**
  service.

## Usage

### sf output

Use functions with the `_sf` suffix to return results as **sf** objects:


``` r
library(nominatimlite)

# Search for Pizza Hut locations in California.

CA <- geo_lite_sf("California", points_only = FALSE)

pizzahut <- geo_lite_sf(
  "Pizza Hut, California",
  limit = 50,
  custom_query = list(countrycodes = "us")
)

library(ggplot2)

ggplot(CA) +
  geom_sf() +
  geom_sf(data = pizzahut, col = "red")
```

::: {#fig-phut}
![Map of Pizza Hut locations in
California.](../man/figures/README-pizzahut-1.png){width="100%"}

Pizza Hut locations in California.
:::

Set `points_only = FALSE` to return polygon and line geometries when they are
available from the **Nominatim API**:


``` r
sol_poly <- geo_lite_sf("Statue of Liberty, NY, USA", points_only = FALSE)

ggplot(sol_poly) +
  geom_sf()
```

::: {#fig-sol}
![Map of the Statue of Liberty
geometry.](../man/figures/README-statue_liberty-1.png){width="100%"}

Statue of Liberty.
:::

### Address search and reverse geocoding

*The examples in this section are adapted from the **tidygeocoder** package.*

Use `geo_lite()` to search for addresses with free-form queries:


``` r
# Create a data frame with addresses.
some_addresses <- dplyr::tribble(
  ~name, ~addr,
  "White House", "1600 Pennsylvania Ave NW, Washington, DC",
  "Transamerica Pyramid", "600 Montgomery St, San Francisco, CA 94111",
  "Willis Tower", "233 S Wacker Dr, Chicago, IL 60606"
)

# Geocode the addresses.
lat_longs <- geo_lite(
  some_addresses$addr,
  lat = "latitude",
  long = "longitude",
  progressbar = FALSE
)
```

By default, `geo_lite()` returns the query, latitude, longitude and address
columns. Set `full_results = TRUE` to return all available fields from the
**Nominatim API**.

::: {#tbl-geo}


|query                                      | latitude|  longitude|address                                                                                                                                       |
|:------------------------------------------|--------:|----------:|:---------------------------------------------------------------------------------------------------------------------------------------------|
|1600 Pennsylvania Ave NW, Washington, DC   | 38.89764|  -77.03655|White House, 1600, Pennsylvania Avenue Northwest, Ward 2, Washington, District of Columbia, 20500, United States                              |
|600 Montgomery St, San Francisco, CA 94111 | 37.79519| -122.40279|Transamerica Pyramid, 600, Montgomery Street, Financial District, South of Market, San Francisco, California, 94111, United States            |
|233 S Wacker Dr, Chicago, IL 60606         | 41.87874|  -87.63596|Willis Tower, 233, South Wacker Drive, Financial District, Loop, Chicago, South Chicago Township, Cook County, Illinois, 60606, United States |



Geocoded addresses.
:::

Use `reverse_geo_lite()` to reverse geocode latitude and longitude coordinates.
The `lat` and `long` arguments use the results from the address search above.
The `address` argument specifies the name of the output column that contains
each single-line address.


``` r
reverse <- reverse_geo_lite(
  lat = lat_longs$latitude,
  long = lat_longs$longitude,
  address = "address_found",
  progressbar = FALSE
)
```

::: {#tbl-rev}


|address_found                                                                                                                   |      lat|        lon|
|:-------------------------------------------------------------------------------------------------------------------------------|--------:|----------:|
|White House, 1600, Pennsylvania Avenue Northwest, Ward 2, Washington, District of Columbia, 20500, United States                | 38.89764|  -77.03655|
|Sky Bar, 600, Montgomery Street, Financial District, South of Market, San Francisco, California, 94111, United States           | 37.79519| -122.40254|
|233, South Wacker Drive, Financial District, Loop, Chicago, South Chicago Township, Cook County, Illinois, 60606, United States | 41.87874|  -87.63589|



Reverse-geocoded addresses.
:::

See the [**Nominatim search API**
documentation](https://nominatim.org/release-docs/latest/api/Search/) for
additional parameters to pass to `custom_query`.

## References