

<!-- README.md is generated from README.qmd. Please edit that file -->

# nominatimlite <a href="https://dieghernan.github.io/nominatimlite/"><img src="man/figures/logo.png" alt="nominatimlite website" align="right" height="139"/></a>

<!-- badges: start -->

[![CRAN
status](https://www.r-pkg.org/badges/version/nominatimlite)](https://CRAN.R-project.org/package=nominatimlite)
[![CRAN
results](https://badges.cranchecks.info/worst/nominatimlite.svg)](https://cran.r-project.org/web/checks/check_results_nominatimlite.html)
[![Downloads](https://cranlogs.r-pkg.org/badges/nominatimlite)](https://CRAN.R-project.org/package=nominatimlite)
[![Nominatim-version](https://img.shields.io/badge/Nominatim-%E2%89%A5_4.4.0-blue)](https://nominatim.org/release-docs/develop/api/Overview/)
[![R-CMD-check](https://github.com/dieghernan/nominatimlite/actions/workflows/check-full.yaml/badge.svg)](https://github.com/dieghernan/nominatimlite/actions/workflows/check-full.yaml)
[![codecov](https://codecov.io/gh/dieghernan/nominatimlite/branch/main/graph/badge.svg?token=jSZ4RIsj91)](https://app.codecov.io/gh/dieghernan/nominatimlite)
[![CodeFactor](https://www.codefactor.io/repository/github/dieghernan/nominatimlite/badge)](https://www.codefactor.io/repository/github/dieghernan/nominatimlite)
[![r-universe](https://dieghernan.r-universe.dev/badges/nominatimlite)](https://dieghernan.r-universe.dev/nominatimlite)
[![Project Status: Active – The project has reached a stable, usable
state and is being actively
developed.](https://www.repostatus.org/badges/latest/active.svg)](https://www.repostatus.org/#active)
[![DOI](https://img.shields.io/badge/DOI-10.32614/CRAN.package.nominatimlite-blue)](https://doi.org/10.32614/CRAN.package.nominatimlite)
[![status](https://tinyverse.netlify.app/status/nominatimlite)](https://CRAN.R-project.org/package=nominatimlite)

<!-- badges: end -->

The goal of **nominatimlite** is to provide a lightweight interface for
geocoding addresses with the [Nominatim
API](https://nominatim.org/release-docs/latest/). It also allows you to
return results as `sf` objects using the **sf** package.

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

## What is Nominatim?

**Nominatim** is a tool for searching
[OpenStreetMap](https://www.openstreetmap.org/) data by name and address
([geocoding](https://wiki.openstreetmap.org/wiki/Geocoding "Geocoding"))
and generating synthetic addresses for OSM points (reverse geocoding).

## Why nominatimlite?

**nominatimlite** accesses the Nominatim API without depending on
**curl**. In some situations, **curl** may not be available or
accessible, so **nominatimlite** uses base R functions instead.

## Recommended packages

Other packages are more complete and mature than **nominatimlite** and
provide similar features:

- [**tidygeocoder**](https://jessecambon.github.io/tidygeocoder/)
  ([Cambon et al. 2021](#ref-R-tidygeocoder)): Provides an interface to
  geocoding services such as Nominatim, Google, TomTom and Mapbox.
- [**osmdata**](https://docs.ropensci.org/osmdata/) ([Padgham et al.
  2017](#ref-R-osmdata)): Downloads spatial data from OpenStreetMap with
  the [Overpass API](https://wiki.openstreetmap.org/wiki/Overpass_API).
- [**arcgeocoder**](https://dieghernan.github.io/arcgeocoder/)
  ([Hernangómez 2024](#ref-R-arcgeocoder)): Provides a lightweight
  interface for geocoding with the ArcGIS REST API service.

## Installation

<div class="pkgdown-release">

Install **nominatimlite** from
[**CRAN**](https://CRAN.R-project.org/package=nominatimlite):

``` r
install.packages("nominatimlite")
```

</div>

<div class="pkgdown-devel">

See the documentation for the development version at
<https://dieghernan.github.io/nominatimlite/dev/>.

You can install the development version of **nominatimlite** with:

``` r
pak::pak("dieghernan/nominatimlite")
```

Alternatively, you can install **nominatimlite** using the
[r-universe](https://dieghernan.r-universe.dev/nominatimlite):

``` r
# Install nominatimlite in R:
install.packages(
  "nominatimlite",
  repos = c(
    "https://dieghernan.r-universe.dev",
    "https://cloud.r-project.org"
  )
)
```

</div>

## Usage

### `sf` objects

With **nominatimlite** you can return `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")
```

<img src="man/figures/README-pizzahut-1.png" style="width:100.0%"
alt="Pizza Hut restaurant locations in California extracted with nominatimlite." />

You can also return polygon and line objects when the Nominatim API
provides them, using the option `points_only = FALSE`:

``` r
# A building, returned as a polygon.
sol_poly <- geo_lite_sf("Statue of Liberty, NY, USA", points_only = FALSE)

ggplot(sol_poly) +
  geom_sf()
```

<img src="man/figures/README-statue_liberty-1.png" style="width:100.0%"
alt="Location of the Statue of Liberty extracted with nominatimlite." />

``` r
# Default, returned as a point.
dayton <- geo_lite_sf("Dayton, OH")
# A US state, returned as a polygon.
ohio_state <- geo_lite_sf("Ohio, USA", points_only = FALSE)
# A river, returned as a line.
ohio_river <- geo_lite_sf("Ohio river", points_only = FALSE)

ggplot() +
  geom_sf(data = ohio_state) +
  geom_sf(data = dayton, color = "red", pch = 4) +
  geom_sf(data = ohio_river, color = "blue")
```

<img src="man/figures/README-line-object-1.png" style="width:100.0%"
alt="Different features named Ohio extracted with nominatimlite." />

### Geocoding and reverse geocoding

*Note: examples are adapted from the **tidygeocoder** package.*

In this first example, we geocode a few addresses with `geo_lite()`:

``` r
library(tibble)

# Create a data frame with addresses.
some_addresses <- 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
)
```

This example returns only latitude, longitude and address columns from
the Nominatim API. Use `full_results = TRUE` to return all available
data from the Nominatim API.

| 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 |

<p class="caption">

Table 1: Example: geocoding addresses.
</p>

To perform reverse geocoding, use `reverse_geo_lite()` to obtain
addresses from geographic coordinates. The arguments are similar to
`geo_lite()`, but now we provide coordinate values with the `lat` and
`long` arguments. The dataset used here is from the geocoding query
above. The single-line address is returned in a column named with the
`address` argument.

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

| address_found | lat | lon |
|:---|---:|---:|
| White House, 1600, Pennsylvania Avenue Northwest, Downtown, Ward 2, Washington, District of Columbia, 20500, United States | 38.89764 | -77.03655 |
| Sky Bar, Mark Twain Place, Financial District, South of Market, San Francisco, California, 94111, United States | 37.79519 | -122.40254 |
| West Adams Street, Financial District, Loop, Chicago, South Chicago Township, Cook County, Illinois, 60675, United States | 41.87874 | -87.63589 |

<p class="caption">

Table 2: Example: reverse geocoding addresses.
</p>

For more advanced users, see the [Nominatim
documentation](https://nominatim.org/release-docs/latest/api/Search/)
for the available parameters.

## Citation

<p>

Hernangómez D (2026). <em>nominatimlite: Interface to the Nominatim
API</em>.
<a href="https://doi.org/10.32614/CRAN.package.nominatimlite">doi:10.32614/CRAN.package.nominatimlite</a>.
<a href="https://dieghernan.github.io/nominatimlite/">https://dieghernan.github.io/nominatimlite/</a>.
</p>

A BibTeX entry for LaTeX users is

    @Manual{R-nominatimlite,
      title = {{nominatimlite}: Interface to the {Nominatim} {API}},
      doi = {10.32614/CRAN.package.nominatimlite},
      author = {Diego Hernangómez},
      year = {2026},
      version = {0.6.0},
      url = {https://dieghernan.github.io/nominatimlite/},
      abstract = {Lightweight interface to the OpenStreetMap Nominatim API <https://nominatim.org/release-docs/latest/>. Extract coordinates from addresses, retrieve addresses from coordinates, look up amenities and addresses, and return results as tibble or sf objects.},
    }

## References

<div id="refs" class="references csl-bib-body hanging-indent">

<div id="ref-R-tidygeocoder" class="csl-entry">

Cambon, Jesse, Diego Hernangómez, Christopher Belanger, and Daniel
Possenriede. 2021. “<span class="nocase">tidygeocoder</span>: An R
Package for Geocoding.” *Journal of Open Source Software* 6 (65): 3544.
<https://doi.org/10.21105/joss.03544>.

</div>

<div id="ref-R-arcgeocoder" class="csl-entry">

Hernangómez, Diego. 2024. *<span class="nocase">arcgeocoder</span>:
Geocoding with the ArcGIS REST API Service*. Version 0.1.0.
<https://doi.org/10.5281/zenodo.10495365>.

</div>

<div id="ref-R-osmdata" class="csl-entry">

Padgham, Mark, Robin Lovelace, Maëlle Salmon, and Bob Rudis. 2017.
“<span class="nocase">osmdata</span>.” *Journal of Open Source Software*
2 (14): 305. <https://doi.org/10.21105/joss.00305>.

</div>

</div>
