Survey123 Tricks of the Trade: Addresses, and the XLSForm geocode appearance
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.
Why the geocode appearance
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:
- Streamlined data entry: The geocode appearance adds an autocomplete experience on top a text question. It can’t get easier than autocompletion as you type!
- Better quality data: Backed by the ArcGIS World Geocoding service, or your own ArcGIS locator, the geocode appearance standardizes user entered data on the fly, reducing typos and inconsistencies.
- Survey results automatically mapped: The location of addresses entered through the geocode appearance can be automatically calculated, helping you visualize and geographically analyze survey responses right away. No post processing needed.
- Data normalization: Using calculations in your form design, you can easily extract address information into multiple fields: postal code, country, latitude and longitude, geocoding score, etc. This enriches your data while keeping your survey design clean.
- Web accessibility: If used in the Survey123 web app, the address question is compatible with screen readers and keyboard navigation, making your online surveys more web accessible.
Getting started
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.
The importance of locators
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.
Configuring locators
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.
Extracting address properties with calculations
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:
- Score: The score property describes the quality of the entered address. A value of 100 means that the user entered an address that matches 100% an existing address in your locator. If the user starts typing an address and selects a candidate from the list, then the user entered text will be replaced by the candidate and you will get a value of 100. If the user ignores the candidates and enters an address that is not listed as a candidate the score will be lower.
- Address: The address property shows the address that more closely matches the user entered address. This is also known as the match address.
- searchText: This property shows the text the end user entered. If the score property is 100, the value of the searchText will be the same as the address property. Otherwise, it will be different.
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.
Using address properties to create data validation rules
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.
Storing the location of an address as a point geometry
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.
Additional resources
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.