---
title: "Get started with nominatimlite"
description: Quick examples showing what **nominatimlite** can do for you.
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 -->



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/)
  [@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` 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")
```

::: {#fig-phut}
![](../man/figures/README-pizzahut-1.png){width="100%"}

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


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

ggplot(sol_poly) +
  geom_sf()
```

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

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()`:


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

::: {#tbl-geo}


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



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.


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



Example: reverse geocoding addresses
:::

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

## References