nominatimlite

CRAN status CRAN results Downloads Nominatim-version R-CMD-check R-hub codecov CodeFactor Project Status: Active – The project has reached a stable, usable state and is being actively developed. DOI status

The goal of nominatimlite is to provide a light interface for geocoding addresses, based on the Nominatim API. It also allows to load spatial objects using the sf package.

Full site with examples and vignettes on https://dieghernan.github.io/nominatimlite/

What is Nominatim?

Nominatim is a tool to search OpenStreetMap data by name and address (geocoding) and to generate synthetic addresses of OSM points (reverse geocoding).

Why nominatimlite?

The main goal of nominatimlite is to access the Nominatim API avoiding the dependency on curl. In some situations, curl may not be available or accessible, so nominatimlite uses base functions to overcome this limitation.

There are other packages much more complete and mature than nominatimlite, that presents similar features:

Installation

Install nominatimlite from CRAN:

install.packages("nominatimlite")

You can install the developing version of nominatimlite with:

remotes::install_github("dieghernan/nominatimlite")

Alternatively, you can install nominatimlite using the r-universe:

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

Usage

sf objects

With nominatimlite you can extract spatial objects easily:

library(nominatimlite)

# Extract some points - Pizza Hut 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")

Locations of Pizza Hut restaurants in California extracted with nominatimlite

You can also extract polygon and line objects (as provided by the Nominatim API) using the option points_only = FALSE:

sol_poly <- geo_lite_sf("Statue of Liberty, NY, USA", points_only = FALSE) # a building - a polygon

ggplot(sol_poly) +
  geom_sf()

Location of Statue of Liberty extracted with nominatimlite

dayton <- geo_lite_sf("Dayton, OH") # default - a point
ohio_state <- geo_lite_sf("Ohio, USA", points_only = FALSE) # a US state - a polygon
ohio_river <- geo_lite_sf("Ohio river", points_only = FALSE) # a river - a line

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

Different features named Ohio extracted with nominatimlite

Geocoding and reverse geocoding

Note: examples adapted from tidygeocoder package

In this first example we will geocode a few addresses using the geo_lite() function:

library(tibble)

# create a dataframe 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")
#>   |                                                          |                                                  |   0%  |                                                          |=================                                 |  33%  |                                                          |=================================                 |  67%  |                                                          |==================================================| 100%

Only latitude and longitude are returned from the geocoder service in this example, but full_results = TRUE can be used to return all of the data from the geocoder service.

query latitude longitude address
1600 Pennsylvania Ave NW, Washington, DC 38.89770 -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.79520 -122.40279 Transamerica Pyramid, 600, Montgomery Street, Financial District, San Francisco, California, 94111, United States
233 S Wacker Dr, Chicago, IL 60606 41.87874 -87.63596 Willis Tower, 233, South Wacker Drive, Printer’s Row, Loop, Chicago, Cook County, Illinois, 60606, United States

To perform reverse geocoding (obtaining addresses from geographic coordinates), we can use the reverse_geo_lite() function. The arguments are similar to the geo_lite() function, but now we specify the input data columns with the lat and long arguments. The dataset used here is from the geocoder query above. The single line address is returned in a column named by the address.

reverse <- reverse_geo_lite(
  lat = lat_longs$latitude, long = lat_longs$longitude,
  address = "address_found"
)
#>   |                                                          |                                                  |   0%  |                                                          |=================                                 |  33%  |                                                          |=================================                 |  67%  |                                                          |==================================================| 100%
address_found lat lon
Zastava Sjedinjenih Američkih Država, Pennsylvania Avenue Northwest, Ward 2, Washington, District of Columbia, 20006, United States 38.89772 -77.03655
Transamerica Pyramid, 600, Montgomery Street, Financial District, San Francisco, California, 94111, United States 37.79520 -122.40279
Willis Tower, 233, South Wacker Drive, Printer’s Row, Loop, Chicago, Cook County, Illinois, 60606, United States 41.87874 -87.63596

For more advance users, see Nominatim docs to check the parameters available.

Citation

Hernangómez D (2024). nominatimlite: Interface with Nominatim API Service. doi:10.32614/CRAN.package.nominatimlite, https://dieghernan.github.io/nominatimlite/.

A BibTeX entry for LaTeX users is

@Manual{R-nominatimlite,
  title = {{nominatimlite}: Interface with {Nominatim} {API} Service},
  doi = {10.32614/CRAN.package.nominatimlite},
  author = {Diego Hernangómez},
  year = {2024},
  version = {0.4.1},
  url = {https://dieghernan.github.io/nominatimlite/},
  abstract = {Lite interface for getting data from OSM service Nominatim <https://nominatim.org/release-docs/latest/>. Extract coordinates from addresses, find places near a set of coordinates and return spatial objects on sf format.},
}

References

Cambon, Jesse, Diego Hernangómez, Christopher Belanger, and Daniel Possenriede. 2021. “tidygeocoder: An R Package for Geocoding.” Journal of Open Source Software 6 (65): 3544. https://doi.org/10.21105/joss.03544.
Hernangómez, Diego. 2024. arcgeocoder: Geocoding with the ArcGIS REST API Service (version 0.1.0). https://doi.org/10.5281/zenodo.10495365.
Padgham, Mark, Robin Lovelace, Maëlle Salmon, and Bob Rudis. 2017. “osmdata.” Journal of Open Source Software 2 (14): 305. https://doi.org/10.21105/joss.00305.