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.

Geopoint question by default

The following should be considered when using geopoints:

  • Only one geopoint question can be used per form, unless it's placed inside a repeat.
  • By default, Survey123 will display WGS84 latitude and longitude values, in a degrees/minutes/seconds format. This display can be changed for a survey by selecting Settings > Map and selecting a different Coordinate Format.
  • 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 5 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.

Location quality expressions

The location accuracy threshold is a single number, a minimum value for the horizontal accuracy of a given location. To warn a user that their location doesn't meet other more complex quality requirements, or constrain them from submitting that location, an expression can be used. There are two columns (and their associated message columns) where these expressions can be entered:

  • The constraint and constraint_message columns can be used to prevent the user from capturing a location in a geopoint question.
  • The bind::esri:warning and bind::esri:warning_message columns introduced in version 3.1 can be used to display a warning to the user if the expression is not met. If the expression is not met, the bar containing the coordinate value at the top of the geopoint question will turn yellow. In this case, the user can still capture the location.
Warning message when response fails to meed location quality expression

An expression can be created in either of these columns using any questions from the survey, but typically questions or parameters related to the survey location would be used. For location parameters that can be used, see the Extract geopoint values section below.

As an example, this expression can be used to ensure that the user has come to a near-standstill before capturing a location, and that horizontal accuracy is better than 5 meters.

pulldata("@geopoint", ., "horizontalAccuracy") < 5 and pulldata("@geopoint", ., "speed") < 0.1

Note:

In practice, while you may want the user to capture a point when standing still, very rarely will a device report a speed value of exactly zero. For this reason, the above example instead searches for a speed of less than 0.1 to introduce an acceptable margin of error.

If it's critical that the location must only be captured under these conditions, this expression should be entered in the constraint column. If it's only a recommendation, entering this expression in the bind::esri:warning column would only display the accompanying warning message to the user. The user could still capture the location in the geopoint question.

The constraint and bind::esri:warning messages will be displayed if the expression in these columns evaluates as false.

For very large or complex expressions, it's best to separate these pulldata functions into individual questions, and then refer to these question names in the expression. For example, to perform the same function as the example above, a question named hAccuracy could use the following calculation:

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

Then, a question named currentSpeed could use this calculation:

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

And the following calculation could be used as the constraint or warning expression for the geopoint question:

(${hAaccuracy} < 5) and (${currentSpeed} < 0.1)

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.

Defaults

A default location can be set for a geopoint question by providing a space-separated set of longitude and latitude values (in decimal degrees) in the default column. For example, -37.814552 144.966071 will cause the geopoint to default to a location in Melbourne, Australia.

Note:

Geopoint defaults located in the Southern Hemisphere will cause an error in Microsoft Excel, as it will attempt to read the value as a formula because it begins with a minus sign (-). In these cases, enter an apostrophe before the first value, and Excel will read this as intended. This causes no changes in behavior in Survey123.

If a default is not provided, the geopoint will automatically update to the device's current location. To force the geopoint not to automatically update its location, set the default value as null.

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 1 meter. As with MGRS, an optional decimal parameter can be used to alter the precision of the grid value.
  • pulldata("@geopoint",${location},"UTM") returns the geopoint as Universal Transverse Mercator (UTM) coordinates. 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") 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 long pressing 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. In the case of the ArcGIS World Geocoder, a JSON object similar to the following will be returned:

{
	"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
		}
	}
}

To extract only a specific value from the JSON object, use a pulldata function similar to the following, which would extract the Match_addr property:

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 in 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")

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 documentation on the reverseGeocode operation.

You can include multiple reverse geocoding calculations without an impact on performance or credits. For example, all of these three calls for individual properties could 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, due to either a change in location, a different request parameter being used, or the original access token expiring.