How the featureType Parameter Affects Reverse Geocoding Results
When performing reverse geocoding requests using the ArcGIS REST API, the featureType parameter plays a significant role in determining the results you get.
While the documentation for reverse geocoding using the ArcGIS REST API provides a search tolerance table for each Feature Type, users sometimes misinterpret how this parameter functions in practice. For instance, it might seem logical that specifying Point Address in the featureType parameter ensures results only within a 50-meter radius, as indicated in the table. But does it really work that way? Let’s explore with an example.
Scenario Setup
In this example we will test reverse geocoding of different locations relative to the actual point location associated with Don Fink Community Park in British Columbia.
- Address: 1155 Abbott Rd, Columbia Shuswap, British Columbia, V0E 1M0
- Location in WGS84 (wkid 4326): −118.946905508147°, 51.23869011702°
- Location in Web Mercator Auxiliary Sphere (wkid 3857): −13241108.95 m, 6663624.36 m
For our test location we will use Don Fink Community Park in British Columbia.
We’ll make reverse geocoding requests from two points near this address:
Request 1: Within 50 Meters
- URL:https://geocode.arcgis.com/arcgis/rest/services/World/GeocodeServer/reverseGeocode?featureTypes=PointAddress&location=-118.9468428,51.2389609&outSR=3857&f=pjson
- Location in WGS84 (wkid 4326): −118.9468428°, 51.2389609°
- Location in Web Mercator Auxiliary Sphere (wkid 3857): -13241108.95 m, 6663624.36 m
- Distance to Point Address: 48.63 meters (calculated using the Pythagorean theorem or an online tool)
Result
The API returns the park’s Point Address feature and an address type of Point Address, as expected.
Reverse geocode requests results for a location within 50 meters of our test park location.
Request 2: Beyond 50 Meters
- URL:https://geocode.arcgis.com/arcgis/rest/services/World/GeocodeServer/reverseGeocode?featureTypes=PointAddress&location=-118.9466242,51.2397049&outSR=3857&f=pjson
- Location in WGS84 (wkid 4326): −118.9466242°, 51.2397049°
- Location in Web Mercator Auxiliary Sphere (wkid 3857): -13241077.64 m, 6663804.78 m
- Distance to Point Address: 183.12 meters
Result
Perhaps surprisingly, this second request still returns the park’s Point Address feature, even though the distance between the search location and the park’s location exceeds 50 meters:
Reverse geocode requests results for a location further than 50 meters from our test park location.
Investigating the Discrepancy
To understand why this happens, let’s adjust the value assigned to the featureType parameter in our requests:
Adjusted Requests
- Near Point:https://geocode.arcgis.com/arcgis/rest/services/World/GeocodeServer/reverseGeocode?featureTypes=PointAddress,POI&location=-118.9468428,51.2389609&outSR=3857&f=pjson
- Far Point:https://geocode.arcgis.com/arcgis/rest/services/World/GeocodeServer/reverseGeocode?featureTypes=PointAddress,POI&location=-118.9466242,51.2397049&outSR=3857&f=pjson
When two values (PointAddress and POI) are included in the featureType parameter, the results align with the search tolerances described in the table:
- Near Point: Returns the park’s address.
- Far Point: No results returned (as it’s outside the 50-meter tolerance).
Reverse geocode requests results showing the address for the park for a location further than 50 meters of the park’s location when multiple values are used in the locationType parameter.
This reveals a crucial insight: the number of values in the featureType parameter affects the behavior of search tolerances.
The Three Scenarios for the featureType Parameter
It turns out that the featureType parameter can operate in one of three ways depending on how many values are passed in:
-
No value specified:
-
The request uses the search tolerances from the hierarchy table.
-
Results may include features from any feature type (except StreetInt, which requires explicit inclusion by including the featureTypes=StreetInt in the reverseGeocode request).
-
-
Single value specified:
-
A fixed search tolerance of 500 meters is applied to the specified Feature Type, overriding that type’s search tolerance value in the hierarchy table.
-
-
Multiple values specified:
-
The request uses the search tolerances associated with each value from the hierarchy table.
-
Returning to our example above, we can now see why specifying only the Point Address value in the featureType parameter applied a 500-meter search tolerance instead of the 50-meter tolerance indicated in the table, explaining why the far point returned the park’s address. By adding a second value (POI), the search tolerances indicated in the hierarchy table were used.
Best Practices for Reverse Geocoding Requests
To ensure your reverse geocoding requests respect the search tolerances in the hierarchy table:
- Use no value or multiple values for the featureType parameter.
- Avoid specifying a single value unless a 500-meter search tolerance meets your needs.
If the feature Type parameter is left blank, the API behaves as though all feature types are included (except StreetInt), which may lead to unexpected results if undesired feature types are returned.
Summary
Understanding the nuances of the featureType parameter can help you achieve more accurate reverse geocoding results. Whether you’re developing applications or conducting spatial analysis, remember:
- Use multiple values or leave the parameter blank for hierarchy table tolerances.
- Be cautious with single values, as they default to a 500-meter search radius.
- Be cautious with leaving the parameter blank as this will return search results using all Feature Types (except StreetInt).
By following these guidelines, you’ll ensure your reverse geocode requests align with both your expectations and the documented behavior in the ArcGIS REST API.