Skip To Content

Geopoints

Geopoint questions allow you to capture a specific location in a survey. While survey responses in Survey123 will always attempt to capture a device's location even if a geopoint question is not included, a visible geopoint question on the form will result in better capture of location information.

The following should be considered when using geopoints:

  • Only one geopoint question can be used per form, unless it's placed inside a repeat.
  • Survey123 will always display WGS84 latitude and longitude values.
  • By default, a geopoint question uses an online basemap. If your survey is to be used offline, see use offline basemaps.

Location accuracy threshold

By default, Survey123 does not check for accuracy in the position values it collects. If position accuracy is important to your survey results, you should define an accuracy threshold with location averaging. This can be done by entering a numerical value in the body::accuracyThreshold column of your geopoint question; this value will be the threshold of accuracy beyond which values are no longer captured when averaging a location.

Error message when response exceeds accuracy threshold of 62 m

When not averaging, the map panel in the Survey123 field app displays a warning if the position accuracy is larger than the defined threshold but doesn't prohibit the user from capturing locations. If you want to capture a location that meets the threshold, wait until there is no warning, and select the location button. Positions that do not meet the accuracy threshold are automatically ignored only while averaging.

3D feature services

By default, Survey123 geopoint questions don't support z-axis (altitude) values; they only capture latitude and longitude in a two-dimensional feature service. You can change this by entering esriFieldTypePointZ into the bind::esriFieldType field of the question, which enables the altitude value to be captured into the feature service. This also allows the altitude field to be altered when specifying a geopoint value.

Calculations

You can populate a geopoint question using the results of other questions. To do this, you first have to understand that the answer of a geopoint question is formatted as a space-separated list of longitude and latitude (in decimal degrees) values followed by optional values, starting with altitude and accuracy (in decimal meters). To populate the answer of a geopoint question, you need to adhere to this structure to produce a valid answer.

Because you can't do this directly when populating from select_one questions, it's recommended that you use the substr() function to help construct a valid answer. For example, the name of the geopoint could be the following:

+059.38330_+018.00000

This value uses a fixed amount of characters for both latitude and longitude, padding the values with zeroes that would normally be truncated with an underscore between the two values, as spaces are not permitted in the name column. This creates a value that can be safely deconstructed with the substr() function to populate the following example of a geopoint question:

substr(${previous_question}, 0, 10) + " " + substr(${previous_question}, -10)

This example takes the first 10 characters of the value (the latitude) and the last 10 characters (the longitude value) and presents them separated by a space as a valid geopoint result.

You can also use the pulldata() function to populate a geopoint question using an attached CSV file. First add the CSV file to your survey's media folder. Then add something similar to the following to your calculation column:

pulldata('Intersections', 'Lat', 'IntersectionID', ${intersection}) + " " + pulldata('Intersections', 'Long', 'IntersectionID', ${intersection})

As with the substr() example, this combines the latitude and longitude values of a location with a space to create a valid answer for a geopoint question based on a previous question.

Examples of both of these in action can be found in the samples in Survey123 Connect.

Required and read-only

Geopoint questions automatically populate a survey with a location provided by the device if one is available. If a device doesn't provide a valid location in its survey response, Survey123 will return a location of 0,0; this point is in a stretch of ocean off the coast of Africa. Marking the geopoint question as required will prevent the survey from being submitted with this null value, only accepting the survey once either the device provides a location or one is manually submitted.

Marking a geopoint question as read-only will prevent the entering of manual answers. This can be useful for questions where an automatic response is necessary, and a manual response would cause issues with the data set. It's best used with one of the calculations described above, which would provide a discrete geopoint value that users would be unable to alter.

Geosearch and geocode

Starting at Survey123 3.0, geopoint questions include geosearch functionality, allowing users to search for an address or point of interest and have the map zoom to and place the geopoint marker at this location. To use this functionality, select the map in the survey to open a full geopoint view. Type the desired address or location in the text box at the top of the screen, select the correct result from the autocomplete results, and the map will zoom to its location.

The full geopoint view is also capable of reverse geocoding, to display the details of your geopoint. To do this, either press and hold on the location on your map, or press and hold on the coordinate display at the bottom of the screen. The location will be printed above the coordinate display. The reverse geocoded location won't be submitted with your survey response.

By default, the geosearch functionality returns results from the entire world, using ArcGIS World Geocoder to search for the addresses. These options can be changed by pressing the globe option to the left of the search box. This opens a dialog box allowing you to change the search mode between Search everywhere and Search within the visible map extents, or to accept Map coordinate input only. You can also choose to use any geocoder available to your organization, for both geosearching and reverse geocoding. If you're not signed in, you'll only have access to ArcGIS World Geocoder.

Extract geopoint values

To deconstruct a geopoint answer, you can use the pulldata()function to extract the values to populate the values of other questions.

Survey123 enhances the pulldata() function when the @ symbol is used at the beginning of the first parameter. This enhancement allows more than the standard four parameters to be retrieved. Additional parameters can be retrieved from a geopoint question using an enhanced pulldata() function. The following example extracts the horizontal accuracy value from a geopoint question:

pulldata("@geopoint", ${location}, "horizontalAccuracy")

The availability of geopoint properties is hardware dependant. The full list of properties that can be pulled from a geopoint (if available from the device) are listed in the following table:

Property nameDescriptionUnit

x

Longitude, positive value in eastern hemisphere, negative value in western hemisphere

Decimal degrees

y

Latitude, positive value in northern hemisphere, negative value in southern hemisphere

Decimal degrees

z

Altitude, meters above sea level

Meters

horizontalAccuracy

Horizontal accuracy of the x and y coordinates

Meters

verticalAccuracy

Vertical accuracy of the z coordinate

Meters

speed

Ground speed

Meters per second

verticalSpeed

Vertical speed

Meters per second

direction

Direction of travel measured clockwise from north

Decimal degrees

magneticVariation

Angle between magnetic and true north

Decimal degrees

Coordinate format

Starting at Survey123 3.0, the pulldata() function can also be used to extract geopoint values and format them into additional coordinate formats. These coordinate formats also accept the following additional, specific parameters:

  • pulldata("@geopoint",${location},"MGRS") returns the geopoint as a Military Grid Reference System (MGRS) grid value with a precision of 1 meter. By providing an optional decimal parameter, the precision can be changed; for example, pulldata("@geopoint",${location},"MGRS",100) returns a grid value with a precision of 100 meters.
  • pulldata("@geopoint",${location},"USNG") returns the geopoint as a United States National Grid (USNG) grid value with a precision of one meter. As with MGRS, an optional decimal parameter can be used to alter the precision of the grid value.
  • pulldata("@geopoint",${location},"UTM",${UTMZone}) returns the geopoint as Universal Transverse Mercator (UTM) coordinates for the specified UTMZone. This is returned as a JSON object:
    {
    	"band": "S",
    	"easting": 452994,
    	"northing": 4423429,
    	"text": "50S 452994E 4423429N",
    	"type": "UTM",
    	"zone": 50
    }
    These individual values can be extracted using additional parameters. For example, pulldata("@geopoint",${location},"UTM.easting",${UTMZone}) returns only the easting value.
  • pulldata("@geopoint",${location},"DMS") returns the geopoint as degrees, minutes, and seconds. This is returned as a JSON object:
    {
    	"latitudeDegrees": 39,
    	"latitudeHemisphere": "N",
    	"latitudeMinutes": 57,
    	"latitudeSeconds": 36.3,
    	"latitudeText": "39°57'36.3\"N",
    	"longitudeDegrees": 116,
    	"longitudeHemisphere": "E",
    	"longitudeMinutes": 27,
    	"longitudeSeconds": 4,
    	"longitudeText": "116°27'04.0\"E",
    	"text": "39°57'36\"N 116°27'4\"E"
    }
    These individual values can be extracted using additional parameters. For example, pulldata("@geopoint",${location},"DMS.latitudeMinutes") returns only the latitude minutes.
  • Geopoints can also be returned as degrees and decimal minutes using pulldata("@geopoint",${location},"DDM"), or as decimal degrees using pulldata("@geopoint",${location},"DD"). These are also returned as JSON objects and can have individual values extracted with additional parameters in the same manner as the degrees, minutes, and seconds format above.

Reverse geocoding

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 not saved and submitted to the survey. The reverse geocoded value can be obtained from the geopoint using pulldata("@geopoint",${location},"reversegeocode"), which returns the location as a JSON object. Individual properties from the object can be extracted by providing the name of the property, but these properties differ depending on the locator used.

The default locator service for your organization will be used. 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.