# arcgisutils 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. An [`llms.txt`](https://r.esri.com/arcgisutils/llms.txt) file is available to provide context for LLMs when working with this package. ## Key Capabilities **šŸ” Comprehensive Authentication**: - Multiple OAuth2 workflows ([`auth_code()`](https://github.com/R-ArcGIS/arcgisutils/reference/auth.md), [`auth_client()`](https://github.com/R-ArcGIS/arcgisutils/reference/auth.md)) - 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()`](https://github.com/R-ArcGIS/arcgisutils/reference/arc_base_req.md), [`arc_paginate_req()`](https://github.com/R-ArcGIS/arcgisutils/reference/arc_paginate_req.md)) - Robust error detection and user-friendly error messages - URL parsing, service introspection, and metadata extraction ## Installation [arcgisutils](https://github.com/R-ArcGIS/arcgisutils) is part of the [arcgis](https://github.com/R-ArcGIS/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](https://github.com/R-ArcGIS/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()`](https://github.com/R-ArcGIS/arcgisutils/reference/auth.md), [`auth_client()`](https://github.com/R-ArcGIS/arcgisutils/reference/auth.md), [`auth_user()`](https://github.com/R-ArcGIS/arcgisutils/reference/auth.md), [`auth_key()`](https://github.com/R-ArcGIS/arcgisutils/reference/auth.md), and [`auth_binding()`](https://github.com/R-ArcGIS/arcgisutils/reference/auth.md). Additional token validation functions are provided via [`refresh_token()`](https://github.com/R-ArcGIS/arcgisutils/reference/auth.md) and [`validate_or_refresh_token()`](https://github.com/R-ArcGIS/arcgisutils/reference/auth.md). [`auth_code()`](https://github.com/R-ArcGIS/arcgisutils/reference/auth.md) can be used for integrating into Shiny applications, for example, to have individual users log in. We recommend using [`auth_key()`](https://github.com/R-ArcGIS/arcgisutils/reference/auth.md) for authenticating in non-interactive environments (for example scheduled scripts or deployments). Tokens are managed using [`set_arc_token()`](https://github.com/R-ArcGIS/arcgisutils/reference/token.md) and [`unset_arc_token()`](https://github.com/R-ArcGIS/arcgisutils/reference/token.md). They are fetched using [`arc_token()`](https://github.com/R-ArcGIS/arcgisutils/reference/token.md). [`set_arc_token()`](https://github.com/R-ArcGIS/arcgisutils/reference/token.md) can set the token globally or set multiple named environments. Here is a minimal example: ``` r library(arcgisutils) #> #> Attaching package: 'arcgisutils' #> The following object is masked from 'package:base': #> #> %||% ``` ``` r key <- auth_key() set_arc_token(key) ``` Alternatively, tokens can be set based on a key-value pair for multiple environments: ``` r set_arc_token("production" = prod_token, "development" = dev_token) ``` And fetched based on their name via ``` r 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 #> # A data frame: 50 Ɨ 46 #> id owner created modified guid name title type #> * #> 1 ea0cfe… Toro… 2023-03-28 15:02:39 2026-02-02 17:45:21 NA Neig… Neig… Feat… #> 2 64691a… Temp… 2024-01-17 20:01:43 2024-01-17 20:04:45 NA hate… Hate… Feat… #> 3 5e055d… JASo… 2023-04-04 17:36:59 2023-09-07 19:05:06 NA Sher… Feat… #> 4 30644d… MyCi… 2025-03-14 14:55:06 2025-08-20 13:55:24 NA HPD_… HPD … Feat… #> 5 c749e3… open… 2024-02-23 19:36:34 2026-01-09 18:36:21 NA Crim… Feat… #> 6 e0992d… balt… 2023-07-31 20:27:01 2025-01-22 21:21:01 NA Part… Part… Feat… #> 7 2cb53d… KASU… 2019-12-10 19:06:39 2019-12-10 19:14:27 NA Viol… Viol… Feat… #> 8 5dc4e6… iwat… 2023-06-23 22:07:21 2023-08-09 15:33:46 NA Prop… Feat… #> 9 ab92f5… KASU… 2019-12-09 16:16:13 2019-12-10 18:55:20 NA Prop… Prop… Feat… #> 10 94bc33… admi… 2023-08-11 20:09:35 2026-01-09 17:03:25 NA Crim… Feat… #> # ℹ 40 more rows #> # ℹ 38 more variables: typeKeywords , description , tags , #> # snippet , thumbnail , documentation , extent , #> # categories , spatialReference , accessInformation , #> # classification , licenseInfo , culture , properties , #> # advancedSettings , url , proxyFilter , access , #> # size , subInfo , appCategories , industries , … ``` ``` r # Get detailed item information for a portal item arc_item(crime_items$id[1]) #> > #> id: ea0cfecdb1de416884e6b0bf08a9e195 #> title: Neighbourhood Crime Rates Open Data #> owner: TorontoPoliceService ``` ### Developer Utilities Always use [`arc_base_req()`](https://github.com/R-ArcGIS/arcgisutils/reference/arc_base_req.md) 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 #> #> GET https://www.arcgis.com #> Body: empty #> Options: #> * useragent: "arcgisutils v0.4.0.9001" ``` To handle paginated services and requests use [`arc_paginate_req()`](https://github.com/R-ArcGIS/arcgisutils/reference/arc_paginate_req.md) 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()`](https://github.com/R-ArcGIS/arcgisutils/reference/featureset.md) directly from an `sf` object. ``` r 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) #> { #> "geometryType": "esriGeometryPoint", #> "spatialReference": { #> "wkid": 4267 #> }, #> "features": [ #> { #> "geometry": { #> "x": -81.4982290095261, #> "y": 36.43139560823758 #> }, #> "attributes": { #> "AREA": 0.114, #> "CNTY_": 1825.0, #> "PERIMETER": 1.442 #> } #> }, #> { #> "geometry": { #> "x": -81.12512977849917, #> "y": 36.49110847237506 #> }, #> "attributes": { #> "AREA": 0.061, #> "CNTY_": 1827.0, #> "PERIMETER": 1.231 #> } #> } #> ] #> } ``` Feature set json can also be parsed using [`parse_esri_json()`](https://github.com/R-ArcGIS/arcgisutils/reference/parse_esri_json.md). ``` r parse_esri_json(nc_json) #> Simple feature collection with 2 features and 3 fields #> Geometry type: POINT #> Dimension: XY #> Bounding box: xmin: -81.49823 ymin: 36.4314 xmax: -81.12513 ymax: 36.49111 #> Geodetic CRS: NAD27 #> AREA CNTY_ PERIMETER geometry #> 1 0.114 1825 1.442 POINT (-81.49823 36.4314) #> 2 0.061 1827 1.231 POINT (-81.12513 36.49111) ``` 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()`](https://github.com/R-ArcGIS/arcgisutils/reference/validate_crs.md). Convert these to json with `yyjsonr` or `jsonify`. ``` r crs <- validate_crs(27700) jsonify::pretty_json(crs, unbox = TRUE) #> { #> "spatialReference": { #> "wkid": 27700 #> } #> } ``` ### Geoprocessing Services The geoprocessing service framework is completely supported in [arcgisutils](https://github.com/R-ArcGIS/arcgisutils). Here we combine the functionality of the geoprocessing job framework with utilities such as [`as_esri_featureset()`](https://github.com/R-ArcGIS/arcgisutils/reference/featureset.md) 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() #> #> Job ID: j89b6513d04f44037b39748e8d931cb31 #> Status: esriJobExecuting #> Resource: /TraceDownstream #> Params: #> • InputPoints #> • Generalize #> • f ``` Jobs run asynchronously so we can check the status with `job$status` ``` r job$status #> #> @ status: chr "esriJobExecuting" ``` Then, when the job is complete, we can fetch the results applying the result function which is [`parse_gp_feature_record_set()`](https://github.com/R-ArcGIS/arcgisutils/reference/gp_params.md) in this case. ``` r job$results #> $param_name #> [1] "OutputTraceLine" #> #> $data_type #> [1] "GPFeatureRecordSetLayer" #> #> $geometry #> Simple feature collection with 1 feature and 6 fields #> Geometry type: MULTILINESTRING #> Dimension: XY #> Bounding box: xmin: 438895 ymin: 2422310 xmax: 443325 ymax: 2428045 #> Projected CRS: NAD83 / UTM zone 4N + Unknown VCS #> OBJECTID PourPtID Description DataResolution LengthKm #> 1 1 1 NED 10m processed by Esri 10.0 9.489823 #> Shape_Length geometry #> 1 9489.823 MULTILINESTRING ((443325 24... # store and view the results res <- job$results res #> $param_name #> [1] "OutputTraceLine" #> #> $data_type #> [1] "GPFeatureRecordSetLayer" #> #> $geometry #> Simple feature collection with 1 feature and 6 fields #> Geometry type: MULTILINESTRING #> Dimension: XY #> Bounding box: xmin: 438895 ymin: 2422310 xmax: 443325 ymax: 2428045 #> Projected CRS: NAD83 / UTM zone 4N + Unknown VCS #> OBJECTID PourPtID Description DataResolution LengthKm #> 1 1 1 NED 10m processed by Esri 10.0 9.489823 #> Shape_Length geometry #> 1 9489.823 MULTILINESTRING ((443325 24... # plot the resultant geometry plot(st_geometry(res$geometry)) ``` ![](reference/figures/README-unnamed-chunk-17-1.png) ## Learn More To learn more about the R-ArcGIS Bridge project visit the [developer documentation](https://developers.arcgis.com/r-bridge/). # Package index ## Request Utilities - [`arc_host()`](https://github.com/R-ArcGIS/arcgisutils/reference/arc_host.md) : Determines Portal Host - [`arc_token()`](https://github.com/R-ArcGIS/arcgisutils/reference/token.md) [`set_arc_token()`](https://github.com/R-ArcGIS/arcgisutils/reference/token.md) [`unset_arc_token()`](https://github.com/R-ArcGIS/arcgisutils/reference/token.md) [`obj_check_token()`](https://github.com/R-ArcGIS/arcgisutils/reference/token.md) [`check_token_has_user()`](https://github.com/R-ArcGIS/arcgisutils/reference/token.md) : Manage authorization tokens - [`arc_agent()`](https://github.com/R-ArcGIS/arcgisutils/reference/arc_agent.md) : Set user-agent for arcgisutils - [`arc_base_req()`](https://github.com/R-ArcGIS/arcgisutils/reference/arc_base_req.md) : Generate base request - [`arc_paginate_req()`](https://github.com/R-ArcGIS/arcgisutils/reference/arc_paginate_req.md) : Paginate ArcGIS Requests - [`detect_errors()`](https://github.com/R-ArcGIS/arcgisutils/reference/detect_errors.md) [`catch_error()`](https://github.com/R-ArcGIS/arcgisutils/reference/detect_errors.md) : Detect errors in parsed json response ## Authorization - [`auth_code()`](https://github.com/R-ArcGIS/arcgisutils/reference/auth.md) [`auth_client()`](https://github.com/R-ArcGIS/arcgisutils/reference/auth.md) [`auth_binding()`](https://github.com/R-ArcGIS/arcgisutils/reference/auth.md) [`auth_user()`](https://github.com/R-ArcGIS/arcgisutils/reference/auth.md) [`auth_key()`](https://github.com/R-ArcGIS/arcgisutils/reference/auth.md) [`refresh_token()`](https://github.com/R-ArcGIS/arcgisutils/reference/auth.md) [`validate_or_refresh_token()`](https://github.com/R-ArcGIS/arcgisutils/reference/auth.md) : Authorization - [`oauth_provider_arcgis()`](https://github.com/R-ArcGIS/arcgisutils/reference/auth_shiny.md) [`auth_shiny()`](https://github.com/R-ArcGIS/arcgisutils/reference/auth_shiny.md) : Authenticate with Shiny ## Portal - [`search_items()`](https://github.com/R-ArcGIS/arcgisutils/reference/search_items.md) : Search for Portal Items - [`arc_item()`](https://github.com/R-ArcGIS/arcgisutils/reference/arc_item.md) : Portal Item Metadata - [`arc_user()`](https://github.com/R-ArcGIS/arcgisutils/reference/arc_user.md) : User Information - [`arc_group()`](https://github.com/R-ArcGIS/arcgisutils/reference/arc_group.md) : Fetch Group Information - [`arc_group_users()`](https://github.com/R-ArcGIS/arcgisutils/reference/arc_group_users.md) : List users in a group - [`arc_item_data()`](https://github.com/R-ArcGIS/arcgisutils/reference/arc_item_data.md) : Download an Item's Data - [`arc_portal_urls()`](https://github.com/R-ArcGIS/arcgisutils/reference/arc_portal_urls.md) : Organization's URLs - [`arc_portal_users()`](https://github.com/R-ArcGIS/arcgisutils/reference/arc_portal_users.md) : Portal Users - [`arc_user_self()`](https://github.com/R-ArcGIS/arcgisutils/reference/arc_user_self.md) : Discover Authenticated User Metadata - [`arc_self_meta()`](https://github.com/R-ArcGIS/arcgisutils/reference/self.md) [`arc_portal_self()`](https://github.com/R-ArcGIS/arcgisutils/reference/self.md) : Access the Portal Self Resource - [`arc_portal_resources()`](https://github.com/R-ArcGIS/arcgisutils/reference/arc_portal_resources.md) : Portal File Resources - [`arc_portal_servers()`](https://github.com/R-ArcGIS/arcgisutils/reference/arc_portal_servers.md) : List ArcGIS Enterprise Servers - [`item_type()`](https://github.com/R-ArcGIS/arcgisutils/reference/portal_types.md) [`item_keyword()`](https://github.com/R-ArcGIS/arcgisutils/reference/portal_types.md) [`portal_item_keywords()`](https://github.com/R-ArcGIS/arcgisutils/reference/portal_types.md) [`portal_item_types()`](https://github.com/R-ArcGIS/arcgisutils/reference/portal_types.md) : Portal Item Types - [`arc_group_content()`](https://github.com/R-ArcGIS/arcgisutils/reference/content.md) [`arc_user_content()`](https://github.com/R-ArcGIS/arcgisutils/reference/content.md) : Portal Content Items ## Geometry - [`determine_dims()`](https://github.com/R-ArcGIS/arcgisutils/reference/determine_dims.md) [`has_m()`](https://github.com/R-ArcGIS/arcgisutils/reference/determine_dims.md) [`has_z()`](https://github.com/R-ArcGIS/arcgisutils/reference/determine_dims.md) : Determine the dimensions of a geometry object - [`determine_esri_geo_type()`](https://github.com/R-ArcGIS/arcgisutils/reference/determine_esri_geo_type.md) : Determine Esri Geometry type - [`validate_crs()`](https://github.com/R-ArcGIS/arcgisutils/reference/validate_crs.md) : Validate CRS object ## JSON - [`as_esri_geometry()`](https://github.com/R-ArcGIS/arcgisutils/reference/as_esri_geometry.md) : Create Esri JSON Geometry Objects - [`as_features()`](https://github.com/R-ArcGIS/arcgisutils/reference/features.md) [`as_esri_features()`](https://github.com/R-ArcGIS/arcgisutils/reference/features.md) : Create Esri Features - [`as_featureset()`](https://github.com/R-ArcGIS/arcgisutils/reference/featureset.md) [`as_esri_featureset()`](https://github.com/R-ArcGIS/arcgisutils/reference/featureset.md) : Create Esri FeatureSet Objects - [`as_layer()`](https://github.com/R-ArcGIS/arcgisutils/reference/layer_json.md) [`as_layer_definition()`](https://github.com/R-ArcGIS/arcgisutils/reference/layer_json.md) [`as_feature_collection()`](https://github.com/R-ArcGIS/arcgisutils/reference/layer_json.md) : Create Esri layer objects - [`as_extent()`](https://github.com/R-ArcGIS/arcgisutils/reference/as_extent.md) : Convert an object to an extent - [`parse_esri_json()`](https://github.com/R-ArcGIS/arcgisutils/reference/parse_esri_json.md) : Parse Esri JSON ## Geoprocessing Services - [`arc_form_params()`](https://github.com/R-ArcGIS/arcgisutils/reference/arc_form_params.md) [`as_form_params()`](https://github.com/R-ArcGIS/arcgisutils/reference/arc_form_params.md) : Form request parameters - [`arc_job_status()`](https://github.com/R-ArcGIS/arcgisutils/reference/arc_job_status.md) : Geoprocessing Job Status - [`new_gp_job()`](https://github.com/R-ArcGIS/arcgisutils/reference/gp_job.md) : Create a Geoprocessing Service Job - [`gp_job_from_url()`](https://github.com/R-ArcGIS/arcgisutils/reference/gp_job_from_url.md) : Create GP Job from existing URL - [`parse_gp_feature_record_set()`](https://github.com/R-ArcGIS/arcgisutils/reference/gp_params.md) [`as_gp_feature_record_set()`](https://github.com/R-ArcGIS/arcgisutils/reference/gp_params.md) [`parse_gp_record_set()`](https://github.com/R-ArcGIS/arcgisutils/reference/gp_params.md) [`as_record_set()`](https://github.com/R-ArcGIS/arcgisutils/reference/gp_params.md) [`as_gp_raster_layer()`](https://github.com/R-ArcGIS/arcgisutils/reference/gp_params.md) [`gp_linear_unit()`](https://github.com/R-ArcGIS/arcgisutils/reference/gp_params.md) [`as_gp_linear_unit()`](https://github.com/R-ArcGIS/arcgisutils/reference/gp_params.md) [`parse_gp_linear_unit()`](https://github.com/R-ArcGIS/arcgisutils/reference/gp_params.md) [`gp_areal_unit()`](https://github.com/R-ArcGIS/arcgisutils/reference/gp_params.md) [`as_gp_areal_unit()`](https://github.com/R-ArcGIS/arcgisutils/reference/gp_params.md) [`parse_gp_areal_unit()`](https://github.com/R-ArcGIS/arcgisutils/reference/gp_params.md) [`as_gp_date()`](https://github.com/R-ArcGIS/arcgisutils/reference/gp_params.md) [`parse_gp_date()`](https://github.com/R-ArcGIS/arcgisutils/reference/gp_params.md) [`as_spatial_reference()`](https://github.com/R-ArcGIS/arcgisutils/reference/gp_params.md) [`from_spatial_reference()`](https://github.com/R-ArcGIS/arcgisutils/reference/gp_params.md) [`parse_spatial_reference()`](https://github.com/R-ArcGIS/arcgisutils/reference/gp_params.md) [`from_envelope()`](https://github.com/R-ArcGIS/arcgisutils/reference/gp_params.md) : Geoprocessing Parameter Types ## Types - [`as_fields()`](https://github.com/R-ArcGIS/arcgisutils/reference/field_mapping.md) [`infer_esri_type()`](https://github.com/R-ArcGIS/arcgisutils/reference/field_mapping.md) [`fields_as_ptype_df()`](https://github.com/R-ArcGIS/arcgisutils/reference/field_mapping.md) [`ptype_tbl()`](https://github.com/R-ArcGIS/arcgisutils/reference/field_mapping.md) : Esri Field Type Mapping - [`is_date()`](https://github.com/R-ArcGIS/arcgisutils/reference/dates.md) [`date_to_ms()`](https://github.com/R-ArcGIS/arcgisutils/reference/dates.md) [`from_esri_date()`](https://github.com/R-ArcGIS/arcgisutils/reference/dates.md) : Date handling ## Utilities - [`compact()`](https://github.com/R-ArcGIS/arcgisutils/reference/utilities.md) [`` `%||%` ``](https://github.com/R-ArcGIS/arcgisutils/reference/utilities.md) [`check_dots_named()`](https://github.com/R-ArcGIS/arcgisutils/reference/utilities.md) [`data_frame()`](https://github.com/R-ArcGIS/arcgisutils/reference/utilities.md) : General utility functions - [`rbind_results()`](https://github.com/R-ArcGIS/arcgisutils/reference/rbind_results.md) : Combine multiple data.frames - [`arc_url_parse()`](https://github.com/R-ArcGIS/arcgisutils/reference/url.md) [`arc_url_type()`](https://github.com/R-ArcGIS/arcgisutils/reference/url.md) [`is_url()`](https://github.com/R-ArcGIS/arcgisutils/reference/url.md) : Parse an ArcGIS service or content URL into its components ## Requests - [`fetch_layer_metadata()`](https://github.com/R-ArcGIS/arcgisutils/reference/fetch_layer_metadata.md) : Retrieve metadata