Survey123 Tricks of the Trade: Addresses, and the XLSForm geocode appearance

11880
12
09-16-2021 04:22 PM
IsmaelChivite
Esri Notable Contributor
8 12 11.9K

 

 

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.

 

Survey123 web app address autocomplete.gif

 

 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:

  1. 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!
  2. 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.
  3. 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.
  4. 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.
  5. 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.

 

IsmaelChivite_0-1631948408814.png

 

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.

Address_World_Geocode_Locator.gif

 

 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.

 

Address_World_Geocode_Locator_View.gif

 

 

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. 

 

IsmaelChivite_0-1631912008109.png

 

 

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:

 

IsmaelChivite_1-1631948491740.png

 

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

 

IsmaelChivite_2-1631948737624.png

 

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:

 

IsmaelChivite_3-1631948867931.png

 

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:

IsmaelChivite_0-1655740846164.png

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.

 

IsmaelChivite_0-1631912998482.png

 

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.

12 Comments
RyanBohan
Occasional Contributor III

The new address question and functionality looks great.  As a possible enhancement is there a way to use the address or generated geopoint to intersect with a hosted feature polygon layer, or a nearest function to a point?

I would love to able to take a simple address input and return an intersect that they are in Council District 3 and have selected question that only apply to their location.  

My current workflow is to show a basemap with the Council Districts and have the user select from a drop down question after entering their address.  I would rather do this for them.

 

IsmaelChivite
Esri Notable Contributor

@RyanBohan  We can't do a point in polygon query as you suggest, yet. Well, technically you can with a Custom JS Function, but you cannot use them in public surveys so I think that will rule them out. It would be awesome to have something like

pulldata("@featurelayer","<URL to polygon feature layer","Intersects","@geoshape",${address_location})

That way, we could then use pulldata("@json") to extract the attribute you were looking for. Something to think about...

Did you look at the new Dynamic Lists? I wonder if they could be of help for you somehow.

RyanBohan
Occasional Contributor III

Hi Ismael,

  Thank you for the response, you are correct I mostly deal with public surveys.  I will look more into dynamic lists, the Point intersects buffered points (with attribute filter) looks great If I can get everyone to use the field app.  Some users like the ease of the web entry.

  My current work flow is to use a map to allow a user to locate an address and then pass the Council District to the Survey via the URL parameters.  Once the survey launches I then need to ask for their address again.  I don't believe there is a way to pass the address from the search to URL unless I go with a hosted JavaScript map.

FredMitchell
New Contributor III

@IsmaelChivite I'm trying to use some of the features mentioned in this post in my forms, particularly using pulldata to constrain what it entered by subregion and also using a custom locator. For some reason adding these various lines of code has broken the map. If you have time to review my files posted here I would greatly appreciate it! https://community.esri.com/t5/arcgis-survey123-questions/automate-map-zoom-based-on-data-entered-in-...

MayraHernandez
New Contributor III

Hi @IsmaelChivite is there a rule that restricts users from submitting an address that doesn't have a street number? 

I created a survey for code enforcement that includes the geocode appearance - ArcGIS World Locator and some of the surveys that users submitted only display the name of the street and not the full address. We also noticed that some of the addresses that generate in the auto drop down list do not exist in Google or in our data, making it hard for code enforcement officers to locate the location of the violation.

What do you suggest?

Thank you,

Mayra Hernandez 

JaredPilbeam2
MVP Regular Contributor

Hi @IsmaelChivite 

There's a prompt that shows up in my published web survey when an address isn't recognized. I'm using v. 3.13.

JaredPilbeam2_0-1638975275165.png

 

I went into organizational settings > utility services and made sure our geocoding service was listed. It is, and it is even ordered on top of the ESRI World Geocoding Service. And I'm also pulling addresses from a CSV. With all these settings in place I can't seem to avoid this prompt that will surely confuse the end-users.

 

Brownschuh
Occasional Contributor II

I'm a bit confused on the example for storing the location of an address as a point geometry. 

Brownschuh_0-1643659325919.png

In the calculations for the x & y fields, I see a reference to a search_address field, but I am not seeing where that field information is coming from.

AndrewBertapelle
New Contributor

@IsmaelChivite, I was similarly confused by the issue @Brownschuh has raised.  Can you confirm this is simply a typo?  (i.e. ${my_address} vs ${search_address})

IsmaelChivite
Esri Notable Contributor

@Brownschuh   @AndrewBertapelle  My bad! I just fixed the screenshot. Also including it below:

IsmaelChivite_0-1655740917790.png

 

AustinCanty1
New Contributor III

@IsmaelChivite 

Hi Ismael,

I've configured an address question to use a custom view of the ArcGIS World Geocoding service that is limited to a particular region. I've reference the item id for that service in the bind::esri:parameters column.

The question works as expected when using the mobile app, but when submitting from the web browser it still uses my organizations default geocoding service. Any ideas why that might be?

Tiff-Maps
New Contributor III

This is a very helpful post. @IsmaelChivite and team, I am wondering if it can be required to have someone fill in and actually select the right address. Sometimes I have noticed it can be buggy that once you click an address, it doesn't take and only what the user types remains. The geocoding still works -- so setting fields that use @pulldata function as required doesn't work.

Issue is that the value within that field is not consistent. Is there a way to ensure they actually click on the full address, like 123 Main St, Tampa, FL 20202, as opposed to "123 main st tampa"? 

ZachBodenner
MVP Regular Contributor

I'm curious about using this functionality in a survey that has a geoshape question. I would like to have the nearest address automatically entered as the default in the field {location}

My setup:

I've configured my organization's custom address locator. It uses only addresses with our city.

I entered geocode=<ItemID> of the locator in esri-bind-parameters of {location} and set the appearance to geocode. 

I've tried to use  pulldata("@geopoint",${location},"reversegeocode.address.Match_addr",<domainName>/<webAdaptor>/rest/services/<folder>/<locatorName>/GeocodeServer) as the entry for the Default column, but when I actually run a test on the form, the text string in the {location} field is just that string starting with pulldata. I've edited it to say @geoshape, and also to have no default, but the result is the same each time (unless there is no default, in which case it's empty).

If I manually start to enter address in the {location} field, the locator appears to be working fine, leading me to think there's something off about the pulldata function or where that's supposed to be entered? Any advice would be great!