Find Address Candidates

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.

Value

An sf object with 60 columns.

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

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)
#> Classes ‘sf’ and 'data.frame':	3 obs. of  62 variables:
#>  $ input_id    : int  1 1 2
#>  $ result_id   : int  NA NA NA
#>  $ loc_name    : chr  "World" "World" "World"
#>  $ status      : chr  "M" "M" "M"
#>  $ score       : num  100 96.9 96.2
#>  $ match_addr  : chr  "Bellwood Coffee" "1366 Glenwood Ave SE, Atlanta, Georgia, 30316" "510 Flat Shoals Ave SE, Atlanta, Georgia, 30316"
#>  $ long_label  : chr  "Bellwood Coffee, 1366 Glenwood Ave SE, Atlanta, GA, 30316, USA" "1366 Glenwood Ave SE, Atlanta, GA, 30316, USA" "510 Flat Shoals Ave SE, Atlanta, GA, 30316, USA"
#>  $ short_label : chr  "Bellwood Coffee" "1366 Glenwood Ave SE" "510 Flat Shoals Ave SE"
#>  $ addr_type   : chr  "POI" "StreetAddress" "PointAddress"
#>  $ type_field  : chr  "Snacks" NA NA
#>  $ place_name  : chr  "Bellwood Coffee" NA NA
#>  $ place_addr  : chr  "1366 Glenwood Ave SE, Atlanta, Georgia, 30316" "1366 Glenwood Ave SE, Atlanta, Georgia, 30316" "510 Flat Shoals Ave SE, Atlanta, Georgia, 30316"
#>  $ phone       : chr  NA NA NA
#>  $ url         : chr  NA NA NA
#>  $ rank        : num  19 20 20
#>  $ add_bldg    : chr  NA NA NA
#>  $ add_num     : chr  "1366" "1366" "510"
#>  $ add_num_from: chr  NA "1360" NA
#>  $ add_num_to  : chr  NA "1368" NA
#>  $ add_range   : chr  NA "1360-1368" NA
#>  $ side        : chr  NA "L" NA
#>  $ st_pre_dir  : chr  NA NA NA
#>  $ st_pre_type : chr  NA NA NA
#>  $ st_name     : chr  "Glenwood" "Glenwood" "Flat Shoals"
#>  $ st_type     : chr  "Ave" "Ave" "Ave"
#>  $ st_dir      : chr  "SE" "SE" "SE"
#>  $ bldg_type   : chr  NA NA NA
#>  $ bldg_name   : chr  NA NA NA
#>  $ level_type  : chr  NA NA NA
#>  $ level_name  : chr  NA NA NA
#>  $ unit_type   : chr  NA NA NA
#>  $ unit_name   : chr  NA NA NA
#>  $ sub_addr    : chr  NA NA NA
#>  $ st_addr     : chr  "1366 Glenwood Ave SE" "1366 Glenwood Ave SE" "510 Flat Shoals Ave SE"
#>  $ block       : chr  NA NA NA
#>  $ sector      : chr  NA NA NA
#>  $ nbrhd       : chr  NA NA NA
#>  $ district    : chr  NA NA NA
#>  $ city        : chr  "Atlanta" "Atlanta" "Atlanta"
#>  $ metro_area  : chr  NA NA NA
#>  $ subregion   : chr  "DeKalb County" "DeKalb County" "DeKalb County"
#>  $ region      : chr  "Georgia" "Georgia" "Georgia"
#>  $ region_abbr : chr  "GA" "GA" "GA"
#>  $ territory   : chr  NA NA NA
#>  $ zone        : chr  NA NA NA
#>  $ postal      : chr  "30316" "30316" "30316"
#>  $ postal_ext  : chr  NA "2051" "2044"
#>  $ country     : chr  "USA" "USA" "USA"
#>  $ cntry_name  : chr  "United States" "United States" "United States"
#>  $ lang_code   : chr  "ENG" "ENG" "ENG"
#>  $ distance    : num  0 0 0
#>  $ x           : num  -84.3 -84.3 -84.3
#>  $ y           : num  33.7 33.7 33.7
#>  $ display_x   : num  -84.3 -84.3 -84.3
#>  $ display_y   : num  33.7 33.7 33.7
#>  $ xmin        : num  -84.3 -84.3 -84.3
#>  $ xmax        : num  -84.3 -84.3 -84.3
#>  $ ymin        : num  33.7 33.7 33.7
#>  $ ymax        : num  33.7 33.7 33.7
#>  $ ex_info     : chr  NA "BELLWOOD COFFEE" "JOE S COFFEEHOUSE"
#>  $ extents     :List of 3
#>   ..$ : Named num  -84.3 33.7 -84.3 33.7
#>   .. ..- attr(*, "names")= chr [1:4] "xmin" "ymin" "xmax" "ymax"
#>   ..$ : Named num  -84.3 33.7 -84.3 33.7
#>   .. ..- attr(*, "names")= chr [1:4] "xmin" "ymin" "xmax" "ymax"
#>   ..$ : Named num  -84.3 33.7 -84.3 33.7
#>   .. ..- attr(*, "names")= chr [1:4] "xmin" "ymin" "xmax" "ymax"
#>  $ geometry    :sfc_POINT of length 3; first list element:  'XY' num  -84.3 33.7
#>  - attr(*, "sf_column")= chr "geometry"
#>  - attr(*, "agr")= Factor w/ 3 levels "constant","aggregate",..: NA NA NA NA NA NA NA NA NA NA ...
#>   ..- attr(*, "names")= chr [1:61] "input_id" "result_id" "loc_name" "status" ...
#>  - attr(*, "error_requests")= list()