-
Notifications
You must be signed in to change notification settings - Fork 6
/
README.Rmd
212 lines (152 loc) · 7.99 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
---
output: github_document
format: gfm
---
<!-- README.md is generated from README.Rmd. Please edit that file -->
```{r, include = FALSE}
knitr::opts_chunk$set(
collapse = TRUE,
comment = "#>",
fig.path = "man/figures/README-",
out.width = "100%"
)
library(jsonify)
```
# arcgisgeocode
<!-- badges: start -->
[](https://lifecycle.r-lib.org/articles/stages.html#experimental)
[](https://CRAN.R-project.org/package=arcgisgeocode)
[](https://github.com/R-ArcGIS/arcgisgeocode/actions/workflows/R-CMD-check.yaml)
<!-- badges: end -->
arcgisgeocode provides access to ArcGIS geocoding services from R. It supports address candidate identification, batch geocoding, reverse geocoding, and autocomplete suggestions.
## Installation
Install the package from CRAN
``` r
# install from CRAN
install.packages("arcgisgeocode")
```
You can also install the development version from r-universe as a binary for Mac, Windows, or Ubuntu from r-universe like so:
``` r
# install from R-universe
install.packages("arcgisgeocode", repos = "https://r-arcgis.r-universe.dev")
```
Or you can install the package from source which requires Rust to be available. Follow the [rustup instructions](https://rustup.rs/) to install Rust and verify your installation is compatible using [`rextendr::rust_sitrep()`](https://extendr.github.io/rextendr/dev/#sitrep). Then install the development version from GitHub:
``` r
# install pak if not available
if (!requireNamespace("pak")) install.packages("pak")
# install development version of {arcgisgeocode}
pak::pak("r-arcgis/arcgisgeocode")
```
## Usage
By default, the [ArcGIS World Geocoder](https://www.esri.com/en-us/arcgis/products/arcgis-world-geocoder) will be used. This geocoding server provides public access to the [`/findAddressCandidates`](https://developers.arcgis.com/rest/geocode/api-reference/geocoding-find-address-candidates.htm), [`/reverseGeocode`](https://developers.arcgis.com/rest/geocode/api-reference/geocoding-reverse-geocode.htm), and [`/suggest`](https://developers.arcgis.com/rest/geocode/api-reference/geocoding-suggest.htm) endpoints made available via the `find_address_candidates()`, `reverse_geocode()`, and `suggest_places()` functions respectively.
The batch geocoding endpoint [`/geocodeAddresses`](https://developers.arcgis.com/rest/geocode/api-reference/geocoding-geocode-addresses.htm) is available via `geocode_addresses()`. However, this requires the use of an authorization token and may consume credits.
Refer to the ArcGIS World Geocoder [official documentation](https://developers.arcgis.com/rest/geocode/api-reference/overview-world-geocoding-service.htm) for additional information on use restrictions and licensing. For example, a valid token is required to [store the results](#important-storing-results) of geocoding transactions.
### Reverse geocoding
Reverse geocoding takes a location and finds the associated address.
::: callout-tip
A token _is not required_ to use this function.
:::
```{r, include = FALSE}
library(pillar)
options("arcgisgeocode.storage" = "never")
```
```{r}
library(arcgisgeocode)
# Find addresses from locations
rev_res <- reverse_geocode(c(-117.172, 34.052))
# preview results
dplyr::glimpse(rev_res)
```
### Address search
The `find_address_candidates()` function returns geocoding candidate results. The function is vectorized over the input and will perform multiple requests in parallel. Each request geocodes one location at a time.
One or more candidates are returned from the endpoint. You can limit the number of candidates using the `max_locations` argument (with a maximum of 50).
::: callout-tip
A token _is not required_ to use this function.
:::
```{r}
# Find addresses from address search
candidates <- find_address_candidates(
address = "esri",
address2 = "380 new york street",
city = "redlands",
country_code = "usa",
max_locations = 2
)
dplyr::glimpse(candidates[, 1:10])
```
### Suggest locations
Geocoding services can also provide a location suggestion based on a search term and, optionally, a location or extent. The `suggest_places()` function (`/suggest` endpoint) is intended to be used as part of a client-facing application that provides autocomplete suggestions.
In this example we create a search extent around a single point and find suggestions based on the search term `"bellwood"`.
::: callout-tip
A token _is not required_ to use this function.
:::
```{r}
# identify a search point as a simple feature column
location <- sf::st_sfc(
sf::st_point(c(-84.34, 33.74)),
crs = 4326
)
# buffer and create a bbox object to search within the extent
search_extent <- sf::st_bbox(
sf::st_buffer(location, 10)
)
# find suggestions within the bounding box
suggestions <- suggest_places(
"bellwood",
location,
search_extent = search_extent
)
suggestions
```
The result is intended to be provided to `find_address_candidates()` to complete the geocoding process. The column `text` contains the address to geocode. The column `magic_key` is a special identifier that makes it much faster to fetch results. Pass this into the argument `magic_key`.
```{r}
# get address candidate information
# using the text and the magic key
res <- find_address_candidates(
suggestions$text,
magic_key = suggestions$magic_key
)
dplyr::glimpse(res[, 1:10])
```
## *Important*: Storing results
By default, the argument `for_storage = FALSE` meaning that the results of the geocoding operation cannot be persisted. If you intend to persist the results of the geocoding operation, you must set `for_storage = TRUE`.
To learn more about free and paid geocoding operations refer to the [storage parameter documentation](https://developers.arcgis.com/documentation/mapping-apis-and-services/geocoding/services/geocoding-service/#storage-parameter).
## Batch geocoding
Many addresses can be geocoded very quickly using the `geocode_addresses()` function which calls the `/geocodeAddresses` endpoint. Note that this function requires an authorization token. `geocode_addresses()` sends the input addresses in chunks as parallel requests.
Batch geocoding requires a signed in user. Load the [`{arcgisutils}`](https://github.com/r-arcgis/arcgisutils) to authorize and set your token. This example uses the [Geocoding Test Dataset](# https://datacatalog.urban.org/node/6158/revisions/14192/view) from the [Urban Institute](https://www.urban.org/).
::: callout-tip
A token _is required_ to use this function with the World Geocoding Service. It may not be necessary if you are using a private ArcGIS Enterprise service.
:::
```{r, eval = FALSE}
library(arcgisutils)
library(arcgisgeocode)
set_arc_token(auth_user())
# Example dataset from the Urban Institute
fp <- "https://urban-data-catalog.s3.amazonaws.com/drupal-root-live/2020/02/25/geocoding_test_data.csv"
to_geocode <- readr::read_csv(fp, readr::locale(encoding = "latin1"))
geocoded <- to_geocode |>
dplyr::reframe(
geocode_addresses(
address = address,
city = city,
region = state,
postal = zip
)
)
dplyr::glimpse(res[, 1:10])
```
## Using other locators
`{arcgisgeocode}` can be used with other geocoding services, including custom locators hosted on ArcGIS Online or Enterprise. For example, we can use the [AddressNC](https://www.nconemap.gov/pages/addresses) geocoding service [available on ArcGIS Online](https://www.arcgis.com/home/item.html?id=247dfe30ec42476a96926ad9e35f725f).
Create a new `GeocodeServer` object using `geocode_server()`. This geocoder can be passed into the `geocoder` argument to any of the geocoding functions.
```{r}
address_nc <- geocode_server(
"https://services.nconemap.gov/secure/rest/services/AddressNC/AddressNC_geocoder/GeocodeServer",
token = NULL
)
res <- find_address_candidates(
address = "rowan coffee",
city = "asheville",
geocoder = address_nc
)
dplyr::glimpse(res[, 1:10])
```