https://github.com/r-arcgis/arcgisutils
Developer utilities for the R-ArcGIS Bridge. Authenticate with the ArcGIS System, read and write Esri JSON, and more.
https://github.com/r-arcgis/arcgisutils
arcgis r-spatial rstats
Last synced: 8 months ago
JSON representation
Developer utilities for the R-ArcGIS Bridge. Authenticate with the ArcGIS System, read and write Esri JSON, and more.
- Host: GitHub
- URL: https://github.com/r-arcgis/arcgisutils
- Owner: R-ArcGIS
- License: apache-2.0
- Created: 2023-10-17T16:49:59.000Z (over 2 years ago)
- Default Branch: main
- Last Pushed: 2025-10-01T18:11:05.000Z (8 months ago)
- Last Synced: 2025-10-22T05:59:49.265Z (8 months ago)
- Topics: arcgis, r-spatial, rstats
- Language: R
- Homepage: https://developers.arcgis.com/r-bridge/api-reference/arcgisutils/
- Size: 66.6 MB
- Stars: 19
- Watchers: 7
- Forks: 5
- Open Issues: 26
-
Metadata Files:
- Readme: README.Rmd
- Changelog: NEWS.md
- License: LICENSE.md
Awesome Lists containing this project
README
---
output: github_document
format: gfm
---
# arcgisutils 
[](https://github.com/R-ArcGIS/arcgisutils/actions/workflows/R-CMD-check.yaml)
[](https://CRAN.R-project.org/package=arcgisutils)
[](https://extendr.rs/extendr/extendr_api/)
```{r, include = FALSE}
knitr::opts_chunk$set(
collapse = TRUE,
comment = "#>",
fig.path = "man/figures/README-",
out.width = "100%"
)
library(pillar)
```
arcgisutils is the foundational infrastructure package that powers the R-ArcGIS Bridge Data and Location Service ecosystem. It provides sophisticated, production-ready tools for interacting with ArcGIS Online, ArcGIS Enterprise, and ArcGIS Platform via their REST APIs.
## Key Capabilities
**🔐 Comprehensive Authentication**:
- Multiple OAuth2 workflows (`auth_code()`, `auth_client()`)
- API key and legacy token support
- Automatic token refresh and validation
- Integration with ArcGIS Pro via `arcgisbinding`
**🌐 Portal Integration**:
- Advanced content search with filtering, sorting, and pagination
- User, group, and organization metadata management
- Portal item discovery and content management workflows
**⚙️ Geoprocessing Services**:
- Support for the geoprocessing service framework built upon R6 and S7
- Enables users to call their own custom geoprocessing services or build on top of existing services
- R6-based job management (`arc_gp_job`) with real-time status tracking and built-in result parsing
**📄 Esri JSON Ecosystem**:
- Bidirectional conversion between R spatial data and Esri JSON formats
- Support for FeatureSets, geometry objects, field definitions, and spatial reference systems
- Optimized parsing with automatic `sf` integration
**🛠️ Developer Utilities**:
- Standardized HTTP client (`arc_base_req()`, `arc_paginate_req()`)
- Robust error detection and user-friendly error messages
- URL parsing, service introspection, and metadata extraction
## Installation
`{arcgisutils}` is part of the `{arcgis}` metapackage, which provides the complete R-ArcGIS Bridge toolkit. For most users, installing the metapackage is recommended:
```r
install.packages("arcgis")
```
You can also install `{arcgisutils}` individually from CRAN:
```r
install.packages("arcgisutils")
```
To install the development version:
```r
pak::pak("r-arcgis/arcgisutils")
```
### Authentication
Authorization tokens are provided through the functions `auth_code()`, `auth_client()`, `auth_user()`, `auth_key()`, and `auth_binding()`. Additional token validation functions are provided via `refresh_token()` and `validate_or_refresh_token()`.
`auth_code()` can be used for integrating into Shiny applications, for example, to have individual users log in. We recommend using `auth_key()` for authenticating in non-interactive environments (for example scheduled scripts or deployments).
Tokens are managed using `set_arc_token()` and `unset_arc_token()`. They are fetched using `arc_token()`. `set_arc_token()` can set the token globally or set multiple named environments. Here is a minimal example:
```{r, eval=TRUE}
library(arcgisutils)
```
```{r eval=FALSE}
key <- auth_key()
set_arc_token(key)
```
Alternatively, tokens can be set based on a key-value pair for multiple environments:
```{r eval=FALSE}
set_arc_token("production" = prod_token, "development" = dev_token)
```
And fetched based on their name via
```{r eval=FALSE}
arc_token("production")
```
### Portal Integration
Search and discover content across your ArcGIS organization:
```{r}
# Search for feature services containing "crime" data
crime_items <- search_items(
query = "crime",
item_type = "Feature Service",
max_pages = 1
)
crime_items
```
```{r}
# Get detailed item information for a portal item
arc_item(crime_items$id[1])
```
### Developer Utilities
Always use `arc_base_req()` as this will handle setting the user agent and authorization token. The function creates a standardized `httr2` request object:
```{r}
# defaults to arcgis.com
host <- arc_host()
req <- arc_base_req(host)
req
```
To handle paginated services and requests use `arc_paginate_req()` to automatically handle fetching pages.
### Esri JSON
There are also a number of utility functions for creating and parsing Esri JSON. For example we can create an Esri `FeatureSet` json string using `as_esri_featureset()` directly from an `sf` object.
```{r, message=FALSE, warning = FALSE}
library(sf)
# load the NC SIDS dataset and extract centroids
# of the first few rows
nc <- system.file("shape/nc.shp", package = "sf") |>
st_read(quiet = TRUE) |>
st_centroid()
# convert to json
nc_json <- as_esri_featureset(nc[1:2, 1:3])
jsonify::pretty_json(nc_json)
```
Feature set json can also be parsed using `parse_esri_json()`.
```{r}
parse_esri_json(nc_json)
```
Additionally, sf's `crs` object can be converted to a [`spatialReference`](https://developers.arcgis.com/documentation/common-data-types/geometry-objects.htm#GUID-DFF0E738-5A42-40BC-A811-ACCB5814BABC) JSON object using `validate_crs()`. Convert these to json with `yyjsonr` or `jsonify`.
```{r}
crs <- validate_crs(27700)
jsonify::pretty_json(crs, unbox = TRUE)
```
### Geoprocessing Services
The geoprocessing service framework is completely supported in `{arcgisutils}`. Here we combine the functionality of the geoprocessing job framework with utilities such as `as_esri_featureset()` to call the [Trace DownStream Elevation Service](https://developers.arcgis.com/rest/elevation-analysis/trace-downstream/)
```{r}
trace_downstream <- function(
input_points,
point_id_field = NULL,
resolution = NULL,
generalize = FALSE,
token = arc_token()
) {
# create a list of parameters
params <- compact(list(
InputPoints = as_esri_featureset(input_points),
PointIdField = point_id_field,
DataSourceResolution = resolution,
Generalize = as.character(generalize),
f = "json"
))
service_url <- "https://hydro.arcgis.com/arcgis/rest/services/Tools/Hydrology/GPServer/TraceDownstream"
arc_gp_job$new(
base_url = service_url,
params = params,
result_fn = parse_gp_feature_record_set,
token
)
}
```
This new function can be called to start a new job:
```{r}
# create input points
input_points <- st_sfc(
st_point(c(-159.548936, 21.955888)),
crs = 4326
)
# initialze an empty job
job <- trace_downstream(
input_points,
token = auth_user()
)
# start the job
job$start()
```
Jobs run asynchronously so we can check the status with `job$status`
```{r include = FALSE}
Sys.sleep(0.5)
```
```{r}
job$status
```
Then, when the job is complete, we can fetch the results applying the result function which is `parse_gp_feature_record_set()` in this case.
```{r include=FALSE}
Sys.sleep(5)
```
```{r}
job$results
# store and view the results
res <- job$results
res
# plot the resultant geometry
plot(st_geometry(res$geometry))
```
## Learn More
To learn more about the R-ArcGIS Bridge project visit the [developer documentation](https://developers.arcgis.com/r-bridge/).