---
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")
```
{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()
```
{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