Reverse geocoding and feature types

Adapted from https://developers.arcgis.com/rest/geocode/api-reference/geocoding-reverse-geocode.htm.

How reverse geocoding selects a feature

Reverse geocoding converts coordinates into an address. The ArcGIS REST API reverseGeocode operation selects the most relevant feature near the input location by using a prioritized hierarchy of feature types.

The following table lists this hierarchy in descending order of priority. Unless otherwise noted, a feature type is returned only when the distance between the input location and the feature is within the tolerance specified in the Search tolerance column.

Feature type	Search tolerance	Comments
StreetInt	10 meters	Intersections are only returned when featuretypes = "StreetInt" is included in the request.
StreetAddress (near), DistanceMarker or StreetName	3 meters	Candidates of type StreetName are only returned if featuretypes = "StreetName" is included in the request.
POI centroid	25 meters	A business or landmark that can be represented by a point.
Subaddress	10 meters	Subaddress candidates, which can be features such as apartments or floors in a building, may not be returned under certain conditions.
PointAddress	50 meters	A PointAddress match is not returned if it is on the opposite side of the street as the input location, even if it is within 50 meters of the location.
StreetAddress (distant), DistanceMarker or StreetName	100 meters	Candidates of type StreetName are only returned if featuretypes = "StreetName" is included in the request.
POI area	within boundary	A business or landmark that can be represented by an area, such as a large park or university. Not available in all countries.
Postal or Locality area	within boundary	If the input location intersects multiple boundaries, the feature with the smallest area is returned.

Table 1: Adapted from ArcGIS REST API reverseGeocode

In arcgeocoder, the featuretypes argument of arc_reverse_geo() controls which feature types the API can return. With the default featuretypes = NULL, the request does not filter feature types and the full hierarchy in Table 1 applies.

Use featuretypes to restrict results to one or more of the following values:

• "StreetInt"
• "DistanceMarker"
• "StreetAddress"
• "StreetName"
• "POI"
• "Subaddress"
• "PointAddress"
• "Postal"
• "Locality"

Supply multiple feature types as a character vector. arcgeocoder converts the vector to the comma-separated value required by the API.

Single featuretypes value

arc_reverse_geo(..., featuretypes = "PointAddress")

Multiple featuretypes values

arc_reverse_geo(..., featuretypes = c("PointAddress", "StreetAddress"))

Examples

The following examples show how featuretypes affects reverse geocoding results.

library(arcgeocoder)
library(dplyr)

Example 1: Return a POI centroid

This example uses the default featuretypes = NULL. The input location is within the search tolerance of both POI and PointAddress features, but the API returns the higher-priority POI centroid (see Table 1). The Addr_type field identifies the returned feature type.

example_x <- -117.196324
example_y <- 34.059217

api_poi <- arc_reverse_geo(
  x = example_x,
  y = example_y,
  langcode = "EN",
  full_results = TRUE,
  verbose = TRUE
)

api_poi |>
  select(x, y, address, lon, lat, Addr_type) |>
  knitr::kable()

x	y	address	lon	lat	Addr_type
-117.1963	34.05922	1025-1141 W Park Ave, Redlands, CA, 92373, USA	-117.1963	34.05917	StreetAddress

Example 2: Return a StreetAddress match

Set featuretypes = "StreetAddress" to restrict the request to street addresses.

api_address <- arc_reverse_geo(
  x = example_x,
  y = example_y,
  featuretypes = "StreetAddress",
  langcode = "EN",
  full_results = TRUE,
  verbose = TRUE
)

api_address |>
  select(x, y, address, lon, lat, Addr_type) |>
  knitr::kable()

x	y	address	lon	lat	Addr_type
-117.1963	34.05922	1025-1141 W Park Ave, Redlands, CA, 92373, USA	-117.1963	34.05917	StreetAddress

Example 3: Return a Locality match

api_local <- arc_reverse_geo(
  x = example_x,
  y = example_y,
  featuretypes = "Locality",
  langcode = "EN",
  full_results = TRUE,
  verbose = TRUE
)

api_local |>
  select(x, y, address, lon, lat, Addr_type) |>
  knitr::kable()

x	y	address	lon	lat	Addr_type
-117.1963	34.05922	Redlands, CA, USA	-117.1963	34.05922	Locality

Example 4: Request multiple feature types

When a request includes multiple values, the API applies the hierarchy in Table 1 to the requested feature types.

api_multiple <- arc_reverse_geo(
  x = example_x,
  y = example_y,
  featuretypes = c("Locality", "StreetInt", "StreetAddress"),
  langcode = "EN",
  full_results = TRUE,
  verbose = TRUE
)

api_multiple |>
  select(x, y, address, lon, lat, Addr_type) |>
  knitr::kable()

x	y	address	lon	lat	Addr_type
-117.1963	34.05922	1025-1141 W Park Ave, Redlands, CA, 92373, USA	-117.1963	34.05917	StreetAddress

Example 5: Handle no results for a feature type

Only some feature types are available near certain locations. When reverse geocoding the North Pole, the API returns a Locality but does not find a StreetAddress.

When no result is available, arc_reverse_geo() returns a tibble with the requested address column set to NA.

# Reverse geocode the North Pole.

npole <- arc_reverse_geo(x = 0, y = 90, langcode = "EN", full_results = TRUE)

npole |>
  select(x, y, address, lon, lat, Addr_type) |>
  knitr::kable()

x	y	address	lon	lat	Addr_type
0	90	Ozero Shybyndy	0	90	POI

# Request a feature type that is unavailable.
npole2 <- arc_reverse_geo(
  x = 0,
  y = 90,
  langcode = "EN",
  full_results = TRUE,
  featuretypes = "StreetAddress"
)

npole2 |>
  knitr::kable()

x	y	address
0	90	NA

Conclusion

The API can return different results for the same x and y values depending on featuretypes. With featuretypes = NULL, the API selects a result using the hierarchy in Table 1.

A restrictive featuretypes filter may produce no result. Keep the default featuretypes = NULL for general-purpose reverse geocoding.