Find Address Candidates | API Reference | ArcGIS R-Bridge

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':	5 obs. of  65 variables:
#>  $ input_id    : int  1 1 2 2 2
#>  $ result_id   : int  NA NA NA NA NA
#>  $ loc_name    : chr  "World" "World" "World" "World" ...
#>  $ status      : chr  "M" "M" "M" "M" ...
#>  $ score       : num  100 96.9 97.8 96.7 96.2
#>  $ match_addr  : chr  "Bellwood Coffee" "1366 Glenwood Ave SE, Atlanta, Georgia, 30316" "Joe's Coffeehouse EAV" "510 Flat Shoals Ave, Atlanta, Georgia, 30316" ...
#>  $ long_label  : chr  "Bellwood Coffee, 1366 Glenwood Ave SE, Atlanta, GA, 30316, USA" "1366 Glenwood Ave SE, Atlanta, GA, 30316, USA" "Joe's Coffeehouse EAV, 510 Flat Shoals Ave SE, Atlanta, GA, 30316, USA" "510 Flat Shoals Ave, Atlanta, GA, 30316, USA" ...
#>  $ short_label : chr  "Bellwood Coffee" "1366 Glenwood Ave SE" "Joe's Coffeehouse EAV" "510 Flat Shoals Ave" ...
#>  $ addr_type   : chr  "POI" "StreetAddress" "POI" "StreetAddress" ...
#>  $ type_field  : chr  "Snacks" NA "Snacks" NA ...
#>  $ place_name  : chr  "Bellwood Coffee" NA "Joe's Coffeehouse EAV" 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" "510 Flat Shoals Ave, Atlanta, Georgia, 30316" ...
#>  $ phone       : chr  NA NA "(404) 521-1122" NA ...
#>  $ url         : chr  NA NA NA NA ...
#>  $ rank        : num  19 20 19 20 19.5
#>  $ add_bldg    : chr  NA NA NA NA ...
#>  $ add_num     : chr  "1366" "1366" "510" "510" ...
#>  $ add_num_from: chr  NA "1360" NA "492" ...
#>  $ add_num_to  : chr  NA "1368" NA "510" ...
#>  $ add_range   : chr  NA "1360-1368" NA "492-510" ...
#>  $ side        : chr  NA "L" NA "L" ...
#>  $ st_pre_dir  : chr  NA NA NA NA ...
#>  $ st_pre_type : chr  NA NA NA NA ...
#>  $ st_name     : chr  "Glenwood" "Glenwood" "Flat Shoals" "Flat Shoals" ...
#>  $ st_type     : chr  "Ave" "Ave" "Ave" "Ave" ...
#>  $ st_dir      : chr  "SE" "SE" "SE" NA ...
#>  $ bldg_type   : chr  NA NA NA NA ...
#>  $ bldg_name   : chr  NA NA NA NA ...
#>  $ level_type  : chr  NA NA NA NA ...
#>  $ level_name  : chr  NA NA NA NA ...
#>  $ unit_type   : chr  NA NA NA NA ...
#>  $ unit_name   : chr  NA NA NA NA ...
#>  $ sub_addr    : chr  NA NA NA NA ...
#>  $ st_addr     : chr  "1366 Glenwood Ave SE" "1366 Glenwood Ave SE" "510 Flat Shoals Ave SE" "510 Flat Shoals Ave" ...
#>  $ block       : chr  NA NA NA NA ...
#>  $ sector      : chr  NA NA NA NA ...
#>  $ nbrhd       : chr  NA NA NA NA ...
#>  $ district    : chr  NA NA NA NA ...
#>  $ city        : chr  "Atlanta" "Atlanta" "Atlanta" "Atlanta" ...
#>  $ metro_area  : chr  NA NA NA NA ...
#>  $ subregion   : chr  "DeKalb County" "DeKalb County" "DeKalb County" "DeKalb County" ...
#>  $ region      : chr  "Georgia" "Georgia" "Georgia" "Georgia" ...
#>  $ region_abbr : chr  "GA" "GA" "GA" "GA" ...
#>  $ territory   : chr  NA NA NA NA ...
#>  $ zone        : chr  NA NA NA NA ...
#>  $ postal      : chr  "30316" "30316" "30316" "30316" ...
#>  $ postal_ext  : chr  NA "2051" NA NA ...
#>  $ country     : chr  "USA" "USA" "USA" "USA" ...
#>  $ cntry_name  : chr  "United States" "United States" "United States" "United States" ...
#>  $ lang_code   : chr  "ENG" "ENG" "ENG" "ENG" ...
#>  $ distance    : num  0 0 0 0 0
#>  $ x           : num  -84.3 -84.3 -84.3 -84.3 -84.3
#>  $ y           : num  33.7 33.7 33.7 33.7 33.7
#>  $ display_x   : num  -84.3 -84.3 -84.3 -84.3 -84.3
#>  $ display_y   : num  33.7 33.7 33.7 33.7 33.7
#>  $ xmin        : num  -84.3 -84.3 -84.3 -84.3 -84.3
#>  $ xmax        : num  -84.3 -84.3 -84.3 -84.3 -84.3
#>  $ ymin        : num  33.7 33.7 33.7 33.7 33.7
#>  $ ymax        : num  33.7 33.7 33.7 33.7 33.7
#>  $ ex_info     : chr  NA "BELLWOOD COFFEE" NA "JOE S COFFEEHOUSE" ...
#>  $ bldg_comp   : chr  NA NA NA NA ...
#>  $ struc_type  : chr  "Commercial" NA "Commercial" NA ...
#>  $ struc_det   : chr  NA NA NA NA ...
#>  $ extents     :List of 5
#>   ..$ : 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"
#>   ..$ : 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 5; 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:64] "input_id" "result_id" "loc_name" "status" ...
#>  - attr(*, "error_requests")= list()