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()

Your browser is no longer supported. Please upgrade your browser for the best experience. See our browser deprecation post for more details.

You can no longer sign into this site. Go to your ArcGIS portal or the ArcGIS Location Platform dashboard to perform management tasks.

Your ArcGIS portal

Create, manage, and access API keys and OAuth 2.0 developer credentials, hosted layers, and data services.

Your ArcGIS Location Platform dashboard

Manage billing, monitor service usage, and access additional resources.

Learn more about these changes in the What's new in Esri Developers June 2024 blog post.

Close