Reverse Geocode Locations — reverse_geocode • arcgisgeocode

Determines the address for a given point.

Usage

reverse_geocode(
  locations,
  crs = sf::st_crs(locations),
  ...,
  lang_code = NULL,
  feature_type = NULL,
  location_type = c("rooftop", "street"),
  preferred_label_values = c("postalCity", "localCity"),
  for_storage = FALSE,
  geocoder = default_geocoder(),
  token = arc_token(),
  .progress = TRUE
)

Arguments

locations: an sfc_POINT object of the locations to be reverse geocoded.
crs: the CRS of the returned geometries. Passed to sf::st_crs(). Ignored if locations is not an sfc_POINT object.
...: unused.
lang_code: default NULL. An ISO 3166 country code. See iso_3166_codes() for valid ISO codes. Optional.
feature_type: limits the possible match types returned. Must be one of "StreetInt", "DistanceMarker", "StreetAddress", "StreetName", "POI", "Subaddress", "PointAddress", "Postal", or "Locality". Optional.
location_type: default "rooftop". Must be one of "rooftop" or "street". Optional.
preferred_label_values: default NULL. Must be one of "postalCity" or "localCity". Optional.
for_storage: default FALSE. Whether or not the results will be saved for long term storage.
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.

Details

This function utilizes the /reverseGeocode endpoint of a geocoding service. By default, it uses the public ArcGIS World Geocoder.

Intersection matches are only returned when feature_types = "StreetInt". See REST documentation for more.

Location Type

Specifies whether the output geometry shuold be the rooftop point or the street entrance location.
The location_type parameter changes the geometry's placement but does not change the attribute values of X, Y, or DisplayX, and DisplayY.

Storage

Very Important

The argument for_storage is used to determine if the request allows you to persist the results of the query. It is important to note that there are contractual obligations to appropriately set this argument. You cannot save or persist results when for_storage = FALSE (the default).

Execution

The /reverseGeocode endpoint can only handle one address 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

# Find addresses from locations
reverse_geocode(c(-117.172, 34.052))
#> Registered S3 method overwritten by 'jsonify':
#>   method     from    
#>   print.json jsonlite
#> Simple feature collection with 1 feature and 22 fields
#> Geometry type: POINT
#> Dimension:     XY
#> Bounding box:  xmin: -117.172 ymin: 34.05204 xmax: -117.172 ymax: 34.05204
#> Geodetic CRS:  WGS 84
#> # A data frame: 1 × 23
#>   match_addr      long_label short_label addr_type type_field place_name add_num
#> * <chr>           <chr>      <chr>       <chr>     <chr>      <chr>      <chr>  
#> 1 600-620 Home P… 600-620 H… 600-620 Ho… StreetAd… ""         ""         608    
#> # ℹ 16 more variables: address <chr>, block <chr>, sector <chr>,
#> #   neighborhood <chr>, district <chr>, city <chr>, metro_area <chr>,
#> #   subregion <chr>, region <chr>, region_abbr <chr>, territory <chr>,
#> #   postal <chr>, postal_ext <chr>, country_name <chr>, country_code <chr>,
#> #   geometry <POINT [°]>