-
Notifications
You must be signed in to change notification settings - Fork 3
/
README.Rmd
131 lines (88 loc) · 5.11 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
---
output: github_document
---
<!-- README.md is generated from README.Rmd. Please edit that file -->
# getarc
<!-- badges: start -->
[](https://codecov.io/gh/MatthewJWhittle/getarc?branch=master)
<!-- badges: end -->
# Overview
`getarc` is an R wrapper for the [ArcGIS Rest API](https://developers.arcgis.com/rest/services-reference/). It provides access to any data hosted on an ArcGIS Feature or Map Server, including exstensive open datasets ([Arc GIS](https://hub.arcgis.com/search)). It currently only supports functionality for querying data.
- `query_layer` gets data from an arc gis server and supports query operations
- `get_layer_details` gets metadata about a layer such as the field names and maxRecordCount
- `get_token` gets an access token via a web browser login to access private services
# Installation
The package can currently be installed from github:
```{r eval=FALSE}
# Install the development version from GitHub:
install.packages("devtools")
devtools::install_github("matthewjwhittle/getarc")
```
```{r include=FALSE}
devtools::load_all()
```
```{r warning=FALSE, message=FALSE}
library(getarc)
library(sf)
library(tidyverse)
```
# Getting Started
## Downloading Data
The `query_layer` function is used to query and download a layer from an Arc GIS server. The layer is identified by the endpoint url. This can be found by visting the service reference, clicking the API explorer tab and copying the query url (up to "/query?...").
<img src="images/Screenshot 2021-02-24 at 18.36.59.png" width="499"/>
A few endpoint urls are provided with the package for testing in the getarc::endpoints object.
```{r cache = TRUE}
national_parks <- query_layer(endpoint = endpoints$national_parks_england)
glimpse(national_parks)
```
Spatial data is returned as an sf object. It is also possible to query tables on an ArcGIS server or return data without a geometry and this will return a tibble.
```{r}
# Plot the first geometry in the object and add the national park's name as the title
plot(national_parks$geometry[1], main = national_parks$NAME[1])
```
## Performing Queries
The ArcGIS Rest API supports a number of query operations to return only the features you need. All query operations are supported via `query_layer` either as a named argument or via the query argument which accepts a named vector of query parameters and arguments. You can also request a maximum number of features, only certain columns, no geometry or less precise geometry. These options all reduce the amount of data transferred and therefore improve the download speed.
```{r}
one_park <-
query_layer(endpoint = endpoints$national_parks_england,
return_n = 1
)
glimpse(one_park)
```
SQL where queries are supported vie the `where` argument. Here I am requesting only the Yorkshire Dales National Park.
```{r}
yorkshire_dales <-
query_layer(endpoint = endpoints$national_parks_england,
where = "NAME LIKE 'YORKSHIRE DALES'")
plot(yorkshire_dales$geometry, main = yorkshire_dales$NAME)
```
You can also pass in a geometry to perform a spatial query (defaulting to intersects).
```{r}
dales_sssi <- query_layer(endpoints$sssi_england, in_geometry = yorkshire_dales$geometry)
# Plot:
plot(yorkshire_dales$geometry, main = "SSSIs in the Yorkshire Dales National Park")
plot(dales_sssi$geometry, col = "green", add = TRUE)
```
The Making Queries vignette (in development) provides much more detail on how to perform queries with `query_layer`. You can also read the [API documentation](https://developers.arcgis.com/rest/services-reference/query-feature-service-layer-.htm) for further detail on performing queries.
# Authentication
The package supports authentication for private servers. This is either done via `get_token` OAuth 2.0 in a popup web browser or via the `generate_token` where OAuth 2.0 isn't supported. Tokens generated by either function should be passed to the `my_token` argument of `query_layer` to authenticate requests.
To use authentication (with `get_token` only) you need to [set up an ArcGIS developers account](https://developers.arcgis.com/sign-up/) (for free) and create an app. This takes about 5 minutes. Once complete you need to navigate to the app on your dashboard, copy the credentials and set them using `set_credentials`. These are saved securely using the keyring package and now you can use `get_token` to access secured services where you have access.
```{r, eval=FALSE}
# Set Credentials (once)
set_credentials(client_id = "xxxx", client_secret = "xxxx", app_name = "My App")
my_token <- get_token()
## Or:
my_token <- get_token(client_id = "xxxx", client_secret = "xxxx", app_name = "My App")
data <-
query_layer(endpoint = private_endpoint,
# Pass in token for a secured service
my_token = my_token
)
```
# Future Development
Things I am working on supporting at the moment:
- Adding new features to a feature layer via addFeatures
- Appending data to a feature layer via append
Things I would like to do in the future:
- Caching the results of `query_layer`
- Only requesting data that has changed from the cache