arcgisutils

arcgisutils is designed as the backbone of the {arcgis} meta-package.

arcgisutils is a developer oriented package that provides the basic functions to build R packages that work with ArcGIS Location Services. It provides functionality for:

• authorization,
• Esri JSON construction and parsing,
• structuring ArcGIS REST API requests,
• Esri type conversions,
• among other utilities

Installation

Install arcgisutils from CRAN.

install.packages("arcgisutils", repos = "https://r-arcgis.r-universe.dev")

Or, you can install the development version of arcgisutils r-universe with:

install.packages("arcgisutils", repos = "https://r-arcgis.r-universe.dev")

Authorization

Authorization tokens are provided through the functions auth_code(), auth_client(), auth_user(), and auth_binding(). Additional token validation functions are provided via refresh_token() and validate_or_refresh_token().

Tokens are managed in a session based cache using set_arc_token() and unset_arc_token(). They are fetched using arc_token(). Here is a minimal example:

library(arcgisutils)
#> 
#> Attaching package: 'arcgisutils'
#> The following object is masked from 'package:base':
#> 
#>     %||%

tkn <- auth_client()

set_arc_token(tkn)

arc_token()
#> <httr2_token>
#> token_type: bearer
#> access_token: <REDACTED>
#> expires_at: 2024-07-11 09:40:56
#> arcgis_host: https://www.arcgis.com

Alternatively, tokens can be set based on a key-value pair.

set_arc_token("A" = tkn, "B" = tkn)
#> ✔ Named tokens set: `A` and `B`
#> ℹ Access named tokens with `arc_token("name")`

And fetched based on their name via

arc_token("A")
#> <httr2_token>
#> token_type: bearer
#> access_token: <REDACTED>
#> expires_at: 2024-07-11 09:40:56
#> arcgis_host: https://www.arcgis.com

Standardized Requests

The function arc_base_req() is used to create a standardized httr2 request object. It handles authorization tokens and sets a user agent.

host <- arc_host() # use arcgis.com by default

arc_base_req(host)
#> <httr2_request>
#> GET https://www.arcgis.com
#> Body: empty
#> Options:
#> • useragent: 'arcgisutils v0.3.0'

Esri JSON

There are also a number of utility functions for creating and parsing Esri JSON. For example we can create a list that represent an Esri FeatureSet using as_featurset() directly from an sf object. To convert to json, it is recommended to use jsonify::to_json(x, unbox = TRUE).

library(sf)
#> Linking to GEOS 3.11.0, GDAL 3.5.3, PROJ 9.1.0; sf_use_s2() is TRUE

nc <- st_read(system.file("shape/nc.shp", package = "sf"), quiet = TRUE)
nc_json <- as_featureset(nc)

str(nc_json, 1)
#> List of 3
#>  $ geometryType    : chr "esriGeometryPolygon"
#>  $ spatialReference:List of 1
#>  $ features        :List of 100

Alternatively, you can use the set of functions with the _esri_ infix to directly create the json. See the Esri geometry reference page for more on how the conversion functions work.

Additionally, sf’s crs object can be converted to a spatialReference JSON object using validate_crs().

validate_crs(27700)
#> $spatialReference
#> $spatialReference$wkid
#> [1] 27700