find_address_candidates {arcgisgeocode}

Find Address Candidates

Description

Given an address, returns geocode result candidates.

Usage

find_address_candidates(
  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,
  search_extent = NULL,
  location = 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,
  magic_key = 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.

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.

location

an sfc_POINT object that centers the search. 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.

magic_key

a unique identifier returned from suggest_places(). When a magic_key is provided, results are returned faster. Optional.

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

Utilizes the ⁠/findAddressCandidates⁠ endpoint.

The endpoint can only handle one request at a time. To make the operation as performant as possible, requests are sent in parallel using httr2::req_perform_parallel(). The JSON responses are then processed using Rust and returned as an sf object.

Value

An sf object with 60 columns.

Examples

candidates_from_single <- find_address_candidates(
  single_line = "Bellwood Coffee, 1366 Glenwood Ave SE, Atlanta, GA, 30316, USA"
)

candidates_from_parts <- find_address_candidates(
  address = c("Bellwood Coffee", "Joe's coffeehouse"),
  address2 = c("1366 Glenwood Ave SE", "510 Flat Shoals Ave"),
  city = "Atlanta",
  region = "GA",
  postal = "30316",
  country_code = "USA"
)

str(candidates_from_parts)