Survey123 version 3.0 has introduced both geosearching and reverse geocoding functionalities, to allow users to both search for street addresses and places of interest when capturing a location, as well as to retrieve the location of a point already selected. Making full use of reverse geocoding can be difficult, though, and we wanted to make sure people could make the fullest use of it right out the gate. So this blog post will describe everything about the new reverse geocoding functionality that we can, so that you can hit the ground running with it!
Reverse geocoding can be performed in the field app by pressing and holding on the map or coordinates when the full geopoint view is opened, but this is only for confirming the location when it’s being captured; the full geocoded description of the location isn’t saved and submitted to the survey. However, the reverse geocoded value can be obtained from the geopoint and inserted into a field in your survey using pulldata("@geopoint",${location},"reversegeocode"), which returns the location as a JSON object that looks something like the following:
{
"address":{
"Match_addr":"570 St Kilda Rd, Melbourne, Victoria, 3004",
"LongLabel":"570 St Kilda Rd, Melbourne, Victoria, 3004, AUS",
"ShortLabel":"570 St Kilda Rd",
"Addr_type":"PointAddress",
"Type":"",
"PlaceName":"",
"AddNum":"570",
"Address":"570 St Kilda Rd", "Block":"",
"Sector":"",
"Neighborhood":"Melbourne",
"District":"",
"City":"Melbourne",
"MetroArea":"",
"Subregion":"",
"Region":"Victoria",
"Territory":"",
"Postal":"3004",
"PostalExt":"",
"CountryCode":"AUS"
},
"location":{
"x":144.97914150000003,
"y":-37.847384999999996,
"spatialReference":{
"wkid":4326,
"latestWkid":4326
}
}
}
Please note that this blog post uses the ArcGIS World Geocoder for our examples, so be aware that other locators won’t produce exactly the same contents. Also know that, when using these reverse geocoding expressions, ArcGIS credits will be consumed if you're using the ArcGIS World Geocoder.
Individual properties from the object can be extracted by providing the name of the property alongside reversegeocode, separated by periods. These properties themselves differ depending on the locator used, but the format always remains the same. This example would return only the “Match_addr” property seen in the JSON object above.
pulldata("@geopoint",${location},"reversegeocode.address.Match_addr")
The default locator service for your organization will be used when reverse geocoding. To use a different locator service, enter the locator URL as an optional parameter into the function with the format pulldata("@geopoint",${location},"reversegeocode",${locatorURL}). If the service is secured, a proxy item must be configured with access credentials saved in it. For more information, see Requirements for configuring your own locators for ArcGIS Online, or Configure utility services with your portal for ArcGIS Enterprise.
If a locator URL is provided, additional parameters can be provided that will be passed to the URL. As with the properties provided within the JSON object, these parameters differ depending on the locator service used. This example uses the featureTypes parameter, which limits the value returned to a specific type of location, to return only the nearest business or landmark.
pulldata("@geopoint",${location},"reversegeocode.address.Match_addr","https://geocode.arcgis.com/arcgis/rest/services/World/GeocodeServer","featureTypes=" + "POI")
Usually, the ArcGIS World Geocoder has two required parameters that you also need to pass through the URL: location and token. These are provided automatically by Survey123, however; you don’t need to do anything about these.
There’s a few other useful parameters you can use with the ArcGIS World Geocoder:
- langCode can be used to set the language reverse-geocoded addresses are returned in, for countries that have multiple languages available. Remember to define only a two-digit locale code, rather than a full language name.
- locationType specifies whether PointAddress geometry is placed on the rooftop or street entrance of the location. If this parameter isn’t provided, it defaults to street.
- forStorage is automatically passed to the geocoder by the Survey123 app, and is used to allow the result to persist. While usually an optional parameter, in the case of Survey123 it’s treated in the same way as compulsory parameters.
For more information on reverse geocoding URL parameters, including a full list of parameters that can be passed to the URL, see the ArcGIS REST API's documentation on the reverseGeocode operation.
You can include multiple reverse geocoding calculations without an impact on performance or credits. As an example, these three calls for individual properties could all be included:
pulldata("@geopoint",${location},"reversegeocode.address.Match_addr")
pulldata("@geopoint",${location},"reversegeocode.address.LongLabel")
pulldata("@geopoint",${location},"reversegeocode.address.ShortLabel")
A reverse geocode will be performed for the first calculation, which would consume credits. After this, the response is cached, and used for the other two calculations. A new call to the geoservice is only required if the reverse geocode request URL has changed, either due to a change in location, using a different request parameter, or the original access token expiring.
Hopefully, this blog helps you implement reverse geocoding into your own surveys. If you have any other questions or issues about reverse geocoding, feel free to leave them in the comments below, or bring them to the Survey123 booth at the UC!
