In many cases, an address is the most natural and accurate way to specify the location of something. Knowing where things happen, is important as we all know. It is not a coincidence that we see ourselves often entering an address when completing a form. Now, working with addresses has its own challenges: How do you avoid typos? How can you tell the postal code was entered correctly? How do you add address data into a map reliably? The geocode appearance in XLSForm is specifically designed to help you collect addresses with confidence and map your survey responses without effort.
In this blog, I will describe how you, as a survey author, can get the best out of the geocode appearance in Survey123 Connect version 3.13 or newer.
The geocode appearance turns an ordinary text question into a great user experience for collecting address information. This is why the geocode appearance is worth your consideration:
Apply the geocode appearance to a text question in your XLSForm design to get started. If you cannot find the geocode choice in the list of appearances, you can type it in directly.
Next save your changes in the XLSForm to trigger a design preview update in Survey123 Connect. You will now see that your text question has address auto-complete capabilities. That’s not all, it is just a start! You can try your new form in the Survey123 web and field apps.
Note: If you set the geocode appearance of a text question and the Connect preview does not show any change, it is likely that the version of Survey123 Connect you have is prior to version 3.13.
Address auto-completion is powered by either the ArcGIS World Geocoding service or your own ArcGIS locator service. They both provide a well-known collection of addresses that is used to support the predictive text feature in the form.
The smarter you can make the autocomplete behavior, the happier respondents will be and the better data you will get. In the animation below, the locator has been configured to find addresses anywhere in the world. Note that as the user starts entering the address, the list of candidates includes addresses from various countries.
In the next animation, we enter exactly the same address, but the list of candidates is restricted to the city of Redlands. This is because the locator is configured to only look for addresses in Redlands, California.
Restricting your locator to provide candidates just within your area of interest is always a good practice. A more accurate list of candidates is a first step towards better quality data.
When the geocode appearance is set, Survey123 automatically leverages the utility geocoding service of your ArcGIS organization. To better control the candidates shown by the geocode appearance, it is recommended that you configure your organization geocoding utility service to search only for specific types of locations within your area of interest. You can also configure your organization’s geocoding service to use multiple locators.
If your organization’s geocoding service uses the ArcGIS World Geocoding service, you can create a new locator view to refine the candidate search. For example, you can filter addresses by country, geographic extent, etc.
Changes in your organization’s geocoding service configuration are picked up by Survey123 when the form loads. You do not need to republish your survey for the changes to take effect.
Additionally, you can also use the bind::esri:parameters column of your XLSForm to specify the item ID of the ArcGIS locator service or locator view to be used. If you do this, the organization’s geocoding service configuration will be ignored, and the specified locator service will be used instead.
The screenshot below shows how to use the geocode bind::esri:parameter to work with a specific locator service.
Ah! One more thing: If you decide to create your own ArcGIS locator using ArcGIS Enterprise, enable the suggest operation in your service. Otherwise, the geocode appearance will not be able to provide the autocomplete experience without further configuration steps.
As of this release, the geocode appearance cannot work against locator packages. Only locator services are supported.
While it is great to keep the complete addresses as text in a single field, you may want to split out and store separately certain address properties such as the country, city or postal code. Having this information in separate fields will give you extra flexibility to query your survey records and create live dashboards and maps.
Using the pulldata("@json") function you can extract properties from the address entered by the user and store them separately in other fields. Here is an example:
The exact properties you can extract from the address depend on the locator used by the geocode question. In the example above, I show just a few of the many properties you will find when using the ArcGIS World Geocoding service. If you use a custom locator service, the properties present may vary.
To figure out what exact properties you can extract I like to display the json output of the geocode operation by using this calculation: string(pulldata("@json", ${address})). To explore the output in detail, make sure you set the expression in the calculation column of a text question using the multiline appearance. Just in case the json string is too long for the default length of a text question, you will also want to set the value of the bind::esri:fieldLength to 9999999
Use Survey123 Connect to enter an address and see what the json looks like. From there, you will quickly see what properties you can extract.
To finish this section, I want to give you extra details about a few properties that you will always find regardless of the locator you use:
The pulldata("@json") expression as shown above gives you great flexibility to enrich your GIS records with important information you can use later to measure the quality of your addresses or to more easily query survey results.
You can also use pulldata("@json") to build data validation logic in your form. For example, you can build a rule to prevent a user from submitting an address if not within a city, as shown below:
Similarly, you can choose to reject addresses below a threshold geocoding score.
Sometimes, you may want to store the location of the address as a point to automatically show your survey results in a web map, dashboard or analyze your survey results geographically.
Working with some Survey123 users we have found out that compared to a map question, the geocode appearance can help significantly improve the quality of the location data you collect. To many survey respondents, it is much easier to enter an address than to pinpoint the location in a map. If you are collecting locations of well-known addresses, the geocode appearance will generally produce better location quality data than a geopoint question type. An extra advantage of the geocode appearance is that it is more web accessible than a map.
To turn an address into a location, you use a pulldata("@json") to calculate a geopoint. Here is how:
You may want to set the appearance of the geopoint question to hidden, if you want to hide the map from the user, or at least set it to read-only to avoid inconsistencies between the point and the address. Well… or not! That is up to what you really need.
Please note that the use of the ArcGIS World Geocoding service for the purpose of finding addresses to store their location in a feature layer is subject to ArcGIS Online credit consumption. Check the credits consumption by capability section in the ArcGIS Online help.
In this blog I wanted to share some basic tips around the geocode appearance in XLSForm. In truth, there is more to it. You will find more information in the geocode section of the appearance help topic. We also added a specific geocode XLSForm sample in Survey123 Connect. I strongly recommend you have a look at it. You will be able to copy-paste many of the useful expressions I described above.
In addition, the sample also includes more configuration options I did not describe, particularly using the body::esri:style XLSForm column. I will let you discover those on your own. Enjoy the journey.
You must be a registered user to add a comment. If you've already registered, sign in. Otherwise, register and sign in.