Reverse Geocode Locations

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))
#> 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
#>                                     match_addr
#> 1 600-620 Home Pl, Redlands, California, 92374
#>                                  long_label     short_label     addr_type
#> 1 600-620 Home Pl, Redlands, CA, 92374, USA 600-620 Home Pl StreetAddress
#>   type_field place_name add_num     address block sector   neighborhood
#> 1                           608 608 Home Pl              South Redlands
#>   district     city metro_area             subregion     region region_abbr
#> 1          Redlands            San Bernardino County California          CA
#>   territory postal postal_ext  country_name country_code
#> 1            92374            United States          USA
#>                    geometry
#> 1 POINT (-117.172 34.05204)