find_address_candidates: 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
)

Value

An sf object with 60 columns.

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.

Examples

Run this code

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)

Run the code above in your browser using DataLab