Type:	Package
Title:	An Interface to ArcGIS Data Services
Version:	0.4.0
Description:	Enables users of 'ArcGIS Enterprise', 'ArcGIS Online', or 'ArcGIS Platform' to read, write, publish, or manage vector and raster data via ArcGIS location services REST API endpoints https://developers.arcgis.com/rest/.
License:	Apache License (≥ 2)
Encoding:	UTF-8
Imports:	arcgisutils (≥ 0.2.0), arcpbf (≥ 0.1.5), cli, httr2 (≥ 1.0.5), jsonify, lifecycle, RcppSimdJson (≥ 0.1.13), rlang, sf, terra, utils
RoxygenNote:	7.3.2
Suggests:	dbplyr, dplyr, rmarkdown, testthat (≥ 3.0.0), tidyselect, vctrs
Config/testthat/edition:	3
URL:	https://developers.arcgis.com/r-bridge, https://github.com/R-ArcGIS/arcgislayers
BugReports:	https://github.com/R-ArcGIS/arcgislayers/issues
NeedsCompilation:	no
Packaged:	2025-04-15 19:02:53 UTC; josiahparry
Author:	Josiah Parry [aut, cre], Eli Pousson [ctb], Kenneth Vernon [ctb], Martha Bass [ctb]
Maintainer:	Josiah Parry <josiah.parry@gmail.com>
Repository:	CRAN
Date/Publication:	2025-04-15 19:20:08 UTC

Add Features to Feature Layer

Description

Delete features from a feature layer based on object ID, a where clause, or a spatial filter.

Usage

add_features(
  x,
  .data,
  chunk_size = 2000,
  match_on = c("name", "alias"),
  rollback_on_failure = TRUE,
  token = arc_token()
)

update_features(
  x,
  .data,
  match_on = c("name", "alias"),
  token = arc_token(),
  rollback_on_failure = TRUE,
  ...
)

delete_features(
  x,
  object_ids = NULL,
  where = NULL,
  filter_geom = NULL,
  predicate = "intersects",
  rollback_on_failure = TRUE,
  token = arc_token(),
  ...
)

Arguments

Details

For a more detailed guide to adding, updating, and deleting features, view the tutorial on the R-ArcGIS Bridge website.

Regarding the match_on argument:when publishing an object to an ArcGIS Portal from R, the object's names are provided as the alias. The object's names are subject to change according to the standards of the ArcGIS REST API. For example. "Sepal.Length" is changed to "Sepal_Width" in the name field but the alias remains "Sepal.Length". For that reason, we match on the alias name by default. Change this argument to match based on the field name.

Value

• add_features() returns a data.frame with columns objectId, uniqueId, globalId, success

• update_features() returns a list with an element named updateResults which is a data.frame with columns objectId, uniqueId, globalId, success

• delete_features() returns a list with an element named deleteResults which is a data.frame with columns objectId, uniqueId, globalId, success

Examples

## Not run: 
  # this is pseudo-code and will not work
  flayer <- arc_open(furl)

  # add sf objects to existing feature service
  add_features(flayer, sfobj)

  # delete all features
  delete_features(flayer, where = "1 = 1")

  # update features
  update_features(flayer, dfobj)

## End(Not run)

Publish Content

Description

Publishes an sf or data.frame object to an ArcGIS Portal as a FeatureCollection.

Usage

add_item(
  x,
  title,
  description = "",
  tags = character(0),
  snippet = "",
  categories = character(0),
  async = FALSE,
  type = "Feature Service",
  token = arc_token()
)

publish_item(
  item_id,
  publish_params = .publish_params(),
  file_type = "featureCollection",
  token = arc_token()
)

publish_layer(
  x,
  title,
  ...,
  publish_params = .publish_params(title, target_crs = sf::st_crs(x)),
  token = arc_token()
)

.publish_params(
  name = NULL,
  description = NULL,
  copyright = NULL,
  target_crs = 3857,
  max_record_count = 2000L
)

Arguments

Details

• add_item() takes a data.frame like object and uploads it as an item in your portal.

• publish_item() takes an ID of an item in your portal and publishes it as a feature service.

• publish_layer() is a high-level wrapper that first adds an object as an item in your portal and subsequently publishes it for you.

• .publish_params() is a utility function to specify optional publish parameters such as copyright text, and the spatial reference of the published feature collection.

Note that there is only support for feature services meaning that only tables and feature layers can be made by these functions.

Publish Parameters

When publishing an item to a portal, a number of publish parameters can be provided. Most importantly is the targetSR which will be the CRS of the hosted feature service. By default this is EPSG:3857.

publish_layer() will use the CRS of the input object, x, by default. If publishing content in two steps with add_item() and publish_item(), use .publish_params() to craft your publish parameters. Ensure that the CRS provided to target_crs matches that of the item you added with add_item().

Value

A named list containing the url of the newly published service.

Examples

## Not run: 
  nc <- sf::st_read(system.file("shape/nc.shp", package = "sf"))
  x <- nc[1:5, 13]

  token <- auth_code()
  set_arc_token(token)

  publish_res <- publish_layer(
    x, "North Carolina SIDS sample"
  )

## End(Not run)

Open connection to remote resource

Description

Provided a URL, create an object referencing the remote resource. The resultant object acts as a reference to the remote data source.

Usage

arc_open(url, token = arc_token())

Arguments

Details

To extract data from the remote resource utilize arc_select() for objects of class FeatureLayer or Table. For ImageServers, utilize arc_raster().

Value

Depending on the provided URL returns a FeatureLayer, Table, FeatureServer, ImageServer, or MapServer. Each of these objects is a named list containing the properties of the service.

See Also

arc_select arc_raster

Examples

## Not run: 
# FeatureLayer
furl <- paste0(
  "https://services3.arcgis.com/ZvidGQkLaDJxRSJ2/arcgis/rest/services/",
  "PLACES_LocalData_for_BetterHealth/FeatureServer/0"
)

arc_open(furl)

# Table
furl <- paste0(
  "https://services.arcgis.com/P3ePLMYs2RVChkJx/arcgis/rest/services/",
  "USA_Wetlands/FeatureServer/1"
)

arc_open(furl)

# ImageServer
arc_open(
  "https://landsat2.arcgis.com/arcgis/rest/services/Landsat/MS/ImageServer"
)

# FeatureServer
furl <- paste0(
  "https://services3.arcgis.com/ZvidGQkLaDJxRSJ2/arcgis/rest/services/",
  "PLACES_LocalData_for_BetterHealth/FeatureServer"
)

arc_open(furl)

# MapServer
map_url <- paste0(
  "https://services.arcgisonline.com/ArcGIS/rest/services/",
  "World_Imagery/MapServer"
)

arc_open(map_url)

## End(Not run)

Read from an Image Server

Description

Given an ImageServer export an image as a terra SpatRaster object. See terra::rast.

Usage

arc_raster(
  x,
  xmin,
  xmax,
  ymin,
  ymax,
  bbox_crs = NULL,
  crs = sf::st_crs(x),
  width = NULL,
  height = NULL,
  format = "tiff",
  ...,
  raster_fn = NULL,
  token = arc_token()
)

Arguments

Details

Value

An object of class SpatRaster.

Examples

## Not run: 
img_url <- "https://landsat2.arcgis.com/arcgis/rest/services/Landsat/MS/ImageServer"

landsat <- arc_open(img_url)

arc_raster(
  landsat,
  xmin = -71,
  xmax = -67,
  ymin = 43,
  ymax = 47.5,
  bbox_crs = 4326,
  width = 100,
  height = 100
)

## End(Not run)

Read an ArcGIS FeatureLayer, Table, or ImageServer

Description

arc_read() combines the functionality of arc_open() with arc_select() or arc_raster() to read an ArcGIS FeatureLayer, Table, or ImageServer to an sf or SpatRaster object. Optionally, set, check, or modify names for the returned data frame or sf object using the col_names and name_repair parameters. For ease of use and convenience, arc_read() allows users to access and query a FeatureLayer, Table, or ImageServer with a single function call instead of combining arc_open() and arc_select(). The conventions of col_select are based on functions for reading tabular data in the {readr} package.

Usage

arc_read(
  url,
  col_names = TRUE,
  col_select = NULL,
  n_max = Inf,
  name_repair = "unique",
  crs = NULL,
  ...,
  fields = NULL,
  alias = "drop",
  token = arc_token()
)

Arguments

Details

Value

An sf object, a data.frame, or an object of class SpatRaster.

See Also

arc_select(); arc_raster()

Examples

## Not run: 
furl <- "https://sampleserver6.arcgisonline.com/arcgis/rest/services/Census/MapServer/3"

# read entire service
arc_read(furl)

# apply tolower() to column names
arc_read(url, name_repair = tolower)

# use paste0 to prevent CRAN check NOTE
furl <- paste0(
  "https://sampleserver6.arcgisonline.com/arcgis/rest/services/",
  "EmergencyFacilities/FeatureServer/0"
)

# use field aliases as column names
arc_read(furl, alias = "replace")

# read an ImageServer directly
img_url <- "https://landsat2.arcgis.com/arcgis/rest/services/Landsat/MS/ImageServer"

arc_read(
  img_url,
  width = 100, height = 100,
  xmin = -71, ymin = 43,
  xmax = -67, ymax = 47.5,
  bbox_crs = 4326
)

## End(Not run)

Query a Feature Service

Description

arc_select() takes a FeatureLayer, Table, of ImageServer object and returns data from the layer as an sf object or data.frame respectively.

Usage

arc_select(
  x,
  ...,
  fields = NULL,
  where = NULL,
  crs = sf::st_crs(x),
  geometry = TRUE,
  filter_geom = NULL,
  predicate = "intersects",
  n_max = Inf,
  page_size = NULL,
  token = arc_token()
)

Arguments

Details

See reference documentation for possible arguments.

FeatureLayers can contain very dense geometries with a lot of coordinates. In those cases, the feature service may time out before all geometries can be returned. To address this issue, we can reduce the number of features returned per each request by reducing the value of the page_size parameter.

arc_select() works by sending a single request that counts the number of features that will be returned by the current query. That number is then used to calculate how many "pages" of responses are needed to fetch all the results. The number of features returned (page size) is set to the maxRecordCount property of the layer by default. However, by setting page_size to be smaller than the maxRecordCount we can return fewer geometries per page and avoid time outs.

Value

An sf object, or a data.frame

Examples

## Not run: 
# define the feature layer url
furl <- paste0(
  "https://services3.arcgis.com/ZvidGQkLaDJxRSJ2/arcgis/rest",
  "/services/PLACES_LocalData_for_BetterHealth/FeatureServer/0"
)

flayer <- arc_open(furl)

arc_select(
  flayer,
  fields = c("StateAbbr", "TotalPopulation")
)

arc_select(
  flayer,
  fields = c("OBJECTID", "PlaceName"),
  where = "TotalPopulation > 1000000"
)

## End(Not run)

Utility functions

Description

Utility functions

Usage

clear_query(x)

list_fields(x)

pull_field_aliases(x)

list_items(x)

refresh_layer(x)

Arguments

Details

• list_fields() returns a data.frame of the fields in a FeatureLayer or Table

• list_items() returns a data.frame containing the layers or tables in a FeatureServer or MapServer

• clear_query() removes any saved query in a FeatureLayer or Table object

• refresh_layer() syncs a FeatureLayer or Table with the remote resource picking up any changes that may have been made upstream. Returns an object of class x.

• pull_field_aliases() returns a named list of the field aliases from a FeatureLayer or Table

Value

See Details.

Examples

## Not run: 
furl <- paste0(
  "https://services3.arcgis.com/ZvidGQkLaDJxRSJ2/arcgis/rest/services/",
  "PLACES_LocalData_for_BetterHealth/FeatureServer/0"
)

flayer <- arc_open(furl)

# list fields available in a layer
list_fields(flayer)

# remove any queries stored in the query attribute
clear_query(update_params(flayer, outFields = "*"))

# refresh metadata of an object
refresh_layer(flayer)

map_url <- paste0(
  "https://services.arcgisonline.com/ArcGIS/rest/services/",
  "World_Imagery/MapServer"
)

# list all items in a server object
list_items(arc_open(map_url))

## End(Not run)

Create a FeatureServer

Description

Creates an empty FeatureServer with no additional layers.

Usage

create_feature_server(
  service_name,
  description = "",
  crs = 3857,
  capabilities = c("create", "delete", "query", "update", "editing"),
  query_formats = c("json", "geojson"),
  initial_extent = list(xmin = NULL, xmax = NULL, ymin = NULL, ymax = NULL),
  max_record_count = 1000L,
  allow_updates = TRUE,
  copyright = "",
  has_static_data = FALSE,
  xss_prevention = xss_defaults(),
  token = arc_token()
)

xss_defaults()

Arguments

Details

Value

If a FeatureServer is created successfully, a FeatureServer object is returned based on the newly created feature server's url.

Examples

## Not run: 
  set_arc_token(auth_code())
  create_feature_server("My empty feature server")

## End(Not run)

Set coded values for FeatureLayer or Table data frame

Description

encode_field_values() can replace column values based on codedValue type field domains from a corresponding Table or FeatureLayer object created with arc_open().

Usage

encode_field_values(
  .data,
  .layer,
  field = NULL,
  codes = c("replace", "label"),
  call = rlang::caller_env()
)

Arguments

Value

A data.frame with fields encoded with their respective domains.

Examples

layer <- arc_open(
  "https://geodata.baltimorecity.gov/egis/rest/services/Housing/dmxOwnership/MapServer/0"
)

res <- arc_select(
  layer,
  n_max = 100,
  where = "RESPAGCY <> '  '",
  fields = "RESPAGCY"
)
encoded <- encode_field_values(res, layer)
table(encoded$RESPAGCY)

Extract a layer from a Feature or Map Server

Description

These helpers provide easy access to the layers contained in a FeatureServer, MapServer, or GroupLayer.

Usage

get_layer(x, id = NULL, name = NULL, token = arc_token())

get_all_layers(x, token = arc_token())

get_layers(x, id = NULL, name = NULL, token = arc_token())

Arguments

Details

The id and name arguments must match the field values of the respective names as seen in the output of list_items()

Value

• get_layer() returns a single FeatureLayer or Table based on its ID

• get_layers() returns a list of the items specified by the id or name argument

• get_all_layers() returns a named list with an element layers and tables. Each a list containing FeatureLayer and Tables respectively.

Examples

## Not run: 
  # FeatureServer
  furl <- paste0(
    "https://services3.arcgis.com/ZvidGQkLaDJxRSJ2/arcgis/rest/services/",
    "PLACES_LocalData_for_BetterHealth/FeatureServer"
  )

  fserv <- arc_open(furl)

  fserv
  get_layer(fserv, 0)
  get_layers(fserv, name = c("Tracts", "ZCTAs"))
  get_all_layers(fserv)

## End(Not run)

Get Estimates

Description

Get Estimates

Usage

get_layer_estimates(x, token = arc_token())

Arguments

Value

A named list containing all estimate info. If extent is present, it is available as an object of class bbox.

References

ArcGIS REST Doc

Examples

furl <- paste0(
  "https://services.arcgis.com/P3ePLMYs2RVChkJx/ArcGIS/rest/services/",
  "USA_Counties_Generalized_Boundaries/FeatureServer/0"
)

county_fl <- arc_open(furl)
get_layer_estimates(county_fl)

List Available Raster Funcitons

Description

This function returns the rasterFunctionInfos field of the ImageServer's metadata as a data.frame. If the field does not exist then an error is emitted.

Usage

list_service_raster_fns(
  x,
  arg = rlang::caller_arg(x),
  call = rlang::caller_call()
)

Arguments

Value

a data.frame of the available raster functions.

Examples

## Not run: 
# use paste to avoid cran note
furl <- paste0(
  "https://di-usfsdata.img.arcgis.com/arcgis/rest/services",
  "/FIA_BIGMAP_2018_Species_Aboveground_Biomass/ImageServer"
)

service <- arc_open(furl)
raster_fns <- list_service_raster_fns(service)
head(raster_fns)

## End(Not run)

Prepare JSON for use as a spatial filter based on feature geometry or bounding box input

Description

prepare_spatial_filter() prepares a named list with ESRI JSON geometry for use as a spatial filter based on a a sfc, sfg, or bbox input object.

match_spatial_rel() takes a scalar character vector with a predicate name to a type of ESRI spatial relation.

Usage

prepare_spatial_filter(
  filter_geom,
  crs,
  predicate,
  error_call = rlang::caller_env()
)

match_spatial_rel(predicate, error_call = rlang::caller_env())

Arguments

Details

Using sfc objects as filter_geom

If an sfc object is provided it will be transformed to the layers spatial reference. If the sfc is missing a CRS (or is an sfg object) it is assumed to use the same spatial reference as the FeatureLayer. If the sfc object has multiple features, the features are unioned with sf::st_union(). If an sfc object has MULTIPOLYGON geometry, the features are cast to POLYGON geometry and only the first element is used.

Value

prepare_spatial_filter() returns a named list with the geometryType, geometry (as Esri JSON), and spatial relation predicate.

match_spatial_rel() returns one of the following spatial binary predicates:

• esriSpatialRelIntersects

• esriSpatialRelContains

• esriSpatialRelCrosses

• esriSpatialRelOverlaps

• esriSpatialRelTouches

• esriSpatialRelWithin

Examples

prepare_spatial_filter(sf::st_point(c(0, 5)), 4326, "intersects")

Query and download attachments

Description

Get metadata about attachments associated with features in a layer. Query attachment information using query_layer_attachments() and download attachments using download_attachments().

Usage

query_layer_attachments(
  x,
  definition_expression = "1=1",
  attachments_definition_expression = NULL,
  object_ids = NULL,
  global_ids = NULL,
  attachment_types = NULL,
  keywords = NULL,
  return_metadata = TRUE,
  ...,
  token = arc_token()
)

download_attachments(
  attachments,
  out_dir,
  ...,
  overwrite = FALSE,
  .progress = TRUE,
  token = arc_token()
)

Arguments

Value

query_layer_attachments() returns a data.frame.

download_attachments() returns a list. If an error occurs, the condition is captured and returned in the list. Otherwise the path to the file that was downloaded is returned.

References

ArcGIS REST API Documentation

Examples

## Not run: 
# create a url path that isn't too wide for CRAN
furl <- paste(
  c(
    "https://services1.arcgis.com/hLJbHVT9ZrDIzK0I",
    "arcgis/rest/services/v8_Wide_Area_Search_Form_Feature_Layer___a2fe9c",
    "FeatureServer/0"
  ),
  collapse = "/"
)
# connect to the layer
layer <- arc_open(furl)

# get the attachment info
att <- query_layer_attachments(layer)

# download them to a path
download_attachments(att, "layer_attachments")

## End(Not run)

Set column labels or names based FeatureLayer or Table data frame field aliases

Description

set_layer_aliases() can replace or label column names based on the the field aliases from a corresponding Table or FeatureLayer object created with arc_open(). Optionally repair names using vctrs::vec_as_names().

Usage

set_layer_aliases(
  .data,
  .layer,
  name_repair = "unique",
  alias = c("replace", "label"),
  call = rlang::caller_env()
)

Arguments

Value

A data.frame. When alias = "replace", the column names are modified. When alias = "label" each column has a new label attribute.

Examples

furl <- paste0(
  "https://services.arcgis.com/P3ePLMYs2RVChkJx/ArcGIS/",
  "rest/services/USA_Counties_Generalized_Boundaries/FeatureServer/0"
)

# open the feature service
flayer <- arc_open(furl)

# select first five rows
five_counties <- arc_select(flayer, n_max = 5)

# add aliases
with_aliases <- set_layer_aliases(five_counties, flayer)

# preview the new names
str(with_aliases, give.attr = FALSE)

Truncate a Feature Layer

Description

Removes all features in a Feature Layer or Table and resets the object ID counter. Truncating a Feature Layer does not change the schema of the data (does not add, remove, or alter existing database columns, constraints, or indexes).

Usage

truncate_layer(x, async = FALSE, attachment_only = FALSE, token = arc_token())

Arguments

Value

a named list with the name "success" and a value of TRUE or FALSE

References

ArcGIS Developers Rest API Doc

Examples

## Not run: 

  # authorize using code flow
  set_arc_token(auth_code())

  # create a FeatureLayer object
  flayer <- arc_open("your-feature-layer-url")

  # truncate it
  truncate_layer(flayer)

## End(Not run)

Modify query parameters

Description

update_params() takes named arguments and updates the query.

Usage

update_params(x, ...)

Arguments

Value

An object of the same class as x

Examples

## Not run: 
furl <- paste0(
  "https://services.arcgis.com/P3ePLMYs2RVChkJx/ArcGIS/rest/services/",
  "USA_Major_Cities_/FeatureServer/0"
)

flayer <- arc_open(furl)
update_params(flayer, outFields = "NAME")

## End(Not run)