geocode_addresses {arcgisgeocode}

Batch Geocode Addresses

Description

Gecocode a vector of addresses in batches.

Usage

geocode_addresses(
  single_line = NULL,
  address = NULL,
  address2 = NULL,
  address3 = NULL,
  neighborhood = NULL,
  city = NULL,
  subregion = NULL,
  region = NULL,
  postal = NULL,
  postal_ext = NULL,
  country_code = NULL,
  location = NULL,
  search_extent = NULL,
  category = NULL,
  crs = NULL,
  max_locations = NULL,
  for_storage = FALSE,
  match_out_of_range = NULL,
  location_type = NULL,
  lang_code = NULL,
  source_country = NULL,
  preferred_label_values = NULL,
  batch_size = NULL,
  geocoder = default_geocoder(),
  token = arc_token(),
  .progress = TRUE
)

Arguments

single_line

a character vector of addresses to geocode. If provided other address fields cannot be used. If address is not provided, single_line must be.

address

a character vector of the first part of a street address. Typically used for the street name and house number. But can also be a place or building name. If single_line is not provided, address must be.

address2

a character vector of the second part of a street address. Typically includes a house number, sub-unit, street, building, or place name. Optional.

address3

a character vector of the third part of an address. Optional.

neighborhood

a character vector of the smallest administrative division associated with an address. Typically, a neighborhood or a section of a larger populated place. Optional.

city

a character vector of the next largest administrative division associated with an address, typically, a city or municipality. A city is a subdivision of a subregion or a region. Optional.

subregion

a character vector of the next largest administrative division associated with an address. Depending on the country, a subregion can represent a county, state, or province. Optional.

region

a character vector of the largest administrative division associated with an address, typically, a state or province. Optional.

postal

a character vector of the standard postal code for an address, typically, a three– to six-digit alphanumeric code. Optional.

postal_ext

a character vector of the postal code extension, such as the United States Postal Service ZIP+4 code, provides finer resolution or higher accuracy when also passing postal. Optional.

country_code

default NULL. An ISO 3166 country code. See iso_3166_codes() for valid ISO codes. Optional.

location

an sfc_POINT object that centers the search. Optional.

search_extent

an object of class bbox that limits the search area. This is especially useful for applications in which a user will search for places and addresses within the current map extent. Optional.

category

a scalar character. Place or address type that can be used to filter suggest results. Optional.

crs

the CRS of the returned geometries. Passed to sf::st_crs(). Ignored if locations is not an sfc_POINT object.

max_locations

the maximum number of results to return. The default is 15 with a maximum of 50. Optional.

for_storage

default FALSE. Whether or not the results will be saved for long term storage.

match_out_of_range

set to TRUE by service by default. Matches locations Optional.

location_type

default "rooftop". Must be one of "rooftop" or "street". Optional.

lang_code

default NULL. An ISO 3166 country code. See iso_3166_codes() for valid ISO codes. Optional.

source_country

default NULL. An ISO 3166 country code. See iso_3166_codes() for valid ISO codes. Optional.

preferred_label_values

default NULL. Must be one of "postalCity" or "localCity". Optional.

batch_size

the number of addresses to geocode per request. Uses the suggested batch size property of the geocoder.

geocoder

default default_geocoder().

token

an object of class httr2_token as generated by auth_code() or related function

.progress

default TRUE. Whether a progress bar should be provided.

Details

Addresses are partitioned into batches of up to batch_size elements. The batches are then sent to the geocoding service in parallel using httr2::req_perform_parallel(). The JSON responses are then processed using Rust and returned as an sf object.

Utilizes the ⁠/geocodeAddresses⁠ endpoint.

Value

an sf object

Examples

# Example dataset from the Urban Institute
## Not run: 
fp <- paste0(
  "https://urban-data-catalog.s3.amazonaws.com/",
  "drupal-root-live/2020/02/25/geocoding_test_data.csv"
)
to_geocode <- read.csv(fp)
geocode_addresses(
  address = to_geocode$address,
  city = to_geocode$city,
  region = to_geocode$state,
  postal = to_geocode$zip
)

## End(Not run)