Batch Geocode Addresses

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.

Value

an sf object

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.

Examples

# Example dataset from the Urban Institute
if (FALSE) {
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
)
}