Get started with nominatimlite
Description: Quick examples showing what nominatimlite can do for you.

The goal of nominatimlite is to provide a lightweight interface for geocoding addresses with the Nominatim API. 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 data by name and address (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 (Cambon et al. 2021): Provides an interface to geocoding services such as Nominatim, Google, TomTom and Mapbox.
- osmdata (Padgham et al. 2017): Downloads spatial data from OpenStreetMap with the Overpass API.
- arcgeocoder (Hernangómez 2024): Provides a lightweight interface for geocoding with the ArcGIS REST API service.

## Usage

### `sf` objects

With nominatimlite you can return `sf` objects:

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

Figure 1: Locations of Pizza Hut in California

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

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

    ggplot(sol_poly) +
      geom_sf()

Figure 2: Statue of Liberty

### Geocoding and reverse geocoding

Note: examples are adapted from the tidygeocoder package.

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

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

Table 1: Example: geocoding addresses

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.

    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, 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, 60606, United States | 41.87874 | -87.63589

Table 2: Example: reverse geocoding addresses

For more advanced users, see the Nominatim documentation for the available parameters.

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