-
-
Notifications
You must be signed in to change notification settings - Fork 2
/
README.Rmd
220 lines (167 loc) · 7.43 KB
/
README.Rmd
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
---
output: github_document
bibliography: inst/REFERENCES.bib
link-citations: true
---
<!-- README.md is generated from README.Rmd. Please edit that file -->
```{r, include = FALSE}
knitr::opts_chunk$set(
collapse = TRUE,
comment = "#>",
warning = FALSE,
message = FALSE,
dev = "ragg_png",
tidy = "styler",
fig.path = "man/figures/README-",
dpi = 90,
out.width = "100%"
)
```
# nominatimlite <a href='https://dieghernan.github.io/nominatimlite/'><img src="man/figures/logo.png" align="right" height="139"/></a>
<!-- badges: start -->
[](https://CRAN.R-project.org/package=nominatimlite)
[](https://cran.r-project.org/web/checks/check_results_nominatimlite.html)
[](https://CRAN.R-project.org/package=nominatimlite)
[](https://nominatim.org/release-docs/develop/api/Overview/)
[](https://github.com/dieghernan/nominatimlite/actions/workflows/check-full.yaml)
[](https://github.com/dieghernan/nominatimlite/actions/workflows/rhub.yaml)
[](https://app.codecov.io/gh/dieghernan/nominatimlite)
[](https://www.codefactor.io/repository/github/dieghernan/nominatimlite)
[](https://dieghernan.r-universe.dev/nominatimlite)
[](https://www.repostatus.org/#active)
[](https://doi.org/10.32614/CRAN.package.nominatimlite)
[](https://CRAN.R-project.org/package=nominatimlite)
<!-- badges: end -->
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.
## Installation
Install **nominatimlite** from
[**CRAN**](https://CRAN.R-project.org/package=nominatimlite):
```{r, eval=FALSE}
install.packages("nominatimlite")
```
You can install the developing version of **nominatimlite** with:
```{r, eval=FALSE}
remotes::install_github("dieghernan/nominatimlite")
```
Alternatively, you can install **nominatimlite** using the
[r-universe](https://dieghernan.r-universe.dev/nominatimlite):
```{r, eval=FALSE}
# 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:
```{r pizzahut, fig.alt="Locations of Pizza Hut restaurants in California extracted with nominatimlite"}
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")
```
You can also extract polygon and line objects (as provided by the Nominatim API)
using the option `points_only = FALSE`:
```{r statue_liberty, fig.alt="Location of Statue of Liberty extracted with nominatimlite"}
sol_poly <- geo_lite_sf("Statue of Liberty, NY, USA", points_only = FALSE) # a building - a polygon
ggplot(sol_poly) +
geom_sf()
```
```{r line-object, fig.alt="Different features named Ohio 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")
```
### 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 example}
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")
```
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.
```{r echo=FALSE}
knitr::kable(lat_longs)
```
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"
)
```
```{r, echo = FALSE}
knitr::kable(reverse)
```
For more advance users, see [Nominatim
docs](https://nominatim.org/release-docs/latest/api/Search/) to check the
parameters available.
## Citation
```{r echo=FALSE, results='asis'}
print(citation("nominatimlite"), style = "html")
```
A BibTeX entry for LaTeX users is
```{r echo=FALSE, comment=""}
toBibtex(citation("nominatimlite"))
```
## References