---
title: "Get started with nominatimlite"
output: rmarkdown::html_vignette
desc: >
  Quick examples showing what **nominatimlite** can do for you.
vignette: >
  %\VignetteIndexEntry{Get started with nominatimlite}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
bibliography: references.bib
link-citations: true
---

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



The goal of **nominatimlite** is to provide a light interface for geocoding
addresses, based on the [Nominatim
API](https://nominatim.org/release-docs/latest/). 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](https://www.openstreetmap.org/) data by name and address
([geocoding](https://wiki.openstreetmap.org/wiki/Geocoding "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.

## Recommended packages

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

-   [**tidygeocoder**](https://jessecambon.github.io/tidygeocoder/)
    [@R-tidygeocoder]: Allows to interface with Nominatim, Google, TomTom,
    Mapbox, etc. for geocoding and reverse geocoding.
-   [**osmdata**](https://docs.ropensci.org/osmdata/) [@R-osmdata]: Great for
    downloading spatial data from OpenStreetMap, via the [Overpass
    API](https://wiki.openstreetmap.org/wiki/Overpass_API).
-   [**arcgeocoder**](https://dieghernan.github.io/arcgeocoder/)
    [@R-arcgeocoder]: Lite interface for geocoding with the ArcGIS REST API
    Service.

## Usage

### `sf` objects

With **nominatimlite** you can extract spatial objects easily:


``` r
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 in California](../man/figures/README-pizzahut-1.png){width="100%"}

You can also extract polygon and line objects (if available) 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()
```

![The Statue of
Liberty](../man/figures/README-statue_liberty-1.png){width="100%"}

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


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


``` r
reverse <- reverse_geo_lite(
  lat = lat_longs$latitude, long = lat_longs$longitude,
  address = "address_found"
)
#> 
  |                                                        
  |                                                  |   0%
  |                                                        
  |=================                                 |  33%
  |                                                        
  |=================================                 |  67%
  |                                                        
  |==================================================| 100%
```



|address_found                                                                                                     |      lat|        lon|
|:-----------------------------------------------------------------------------------------------------------------|--------:|----------:|
|White House, 1600, Pennsylvania Avenue Northwest, Ward 2, Washington, District of Columbia, 20500, United States  | 38.89770|  -77.03655|
|Transamerica Pyramid, 600, Montgomery Street, Financial District, San Francisco, California, 94111, United States | 37.79519| -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](https://nominatim.org/release-docs/latest/api/Search/) to check the
parameters available.

## References