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 can 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 meet 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)

Report the 95 percent confidence interval

Your organization may require that collected data be reported at a specific confidence interval (CI). By default, when the accuracy type that is returned is root mean square (RMS), the CI is 68 percent. To report the 95 percent CI in your survey, you need to multiply the horizontal accuracy by 1.7308 and the vertical accuracy by 1.9600. For more information on these conversion factors, see the National Standard for Spatial Data Accuracy.

High-precision accuracy example

In this example, an absolute minimum set of variables must be met, but the user is given discretion to collect a location with some less-strict variables. It may be that there are safety or hazard issues that prevent the user from remaining at the location long enough to meet the preferred requirements. In this case, a warning is shown and the user can decide to capture the location or wait longer.

The absolute minimum accuracy requirement may be as follows:

  • Horizontal accuracy with 95 percent CI is less than two meters.
  • Vertical accuracy with 95 percent CI is less than two meters.
  • Positional Dilution of Precision (PDOP) is less than or equal to 6.0.
  • Five or more satellites are used.

The preferred accuracy requirement may be as follows:

  • Horizontal accuracy with 95 percent CI is less than one meter.
  • Vertical accuracy with 95 percent CI is less than one meter.
  • PDOP is less than or equal to 2.0
  • Seven or more satellites are used.

A question named haccuracy68cep could use the following calculation:

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

Then a question named haccuracy95ci could use the following calculation:

${haccuracy68cep}*1.7308

With similar calculations made for vertical accuracy, the following expression would be entered in the constraintcolumn to represent the absolute minimum accuracy:

${accuracyType} = 0 and ${haccuracy95ci} < 2 and ${vaccuracy95ci} < 2 and ${pdop} <= 6 and ${satellitesInUse} >= 5

The following expression would be entered in the bind::esri:warningcolumn to represent the preferred accuracy. The values used here are typically smaller than those used for the absolute minimum accuracy. Smaller values are preferred, but the larger minimum values can be acceptable.

${accuracyType} = 0 and ${haccuracy95ci} < 1 and ${vaccuracy95ci} < 1 and ${pdop} <= 2 and ${satellitesInUse} >= 7

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::esri:fieldType 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 (default) or height above ellipsoid (if selected in field app settings).

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

positionSourceType

Returns the category of the position source. Potential results are Unknown (0), User (1), System Location (2), External Device (3), and Network Device (4).

N/A

fixType

Returns the type of position fix the coordinate has. Potential results are NoFix (0), GPS (1), DifferentialGPS (2), PrecisePositioningService (3), RTKFixed (4), RTKFloat (5), Estimated (6), Manual (7), Simulator (8), and SBAS (9).

N/A

positionSourceInfo

Returns device information as a JSON object. Useful for debugging and validation. Individual elements can also be returned using full element name. See the following table rows for all available elements.

N/A

positionSourceInfo.pluginName

Returns the name of the internal position source. This is only available for the integrated location provider of the device.

positionSourceInfo.deviceAddress

Returns the address of the device. This is only available for external GNSS receivers.

N/A

positionSourceInfo.deviceName

Returns the name of the device. This is only available for external GNSS receivers.

N/A

positionSourceInfo.deviceType

Indicates the type of external device. Potential results for positionSourceInfo.deviceType are Unknown (-1), Bluetooth (0), Serial Port (1), and Bluetooth LE (2). This is only available for external GNSS receivers.

N/A

positionSourceInfo.networkName

Returns the name of the network position source. This is only available for network location providers.

N/A

positionSourceInfo.networkAddress

Returns the address of the network position source. This is only available for network location providers.

N/A

positionSourceInfo.networkPort

Returns the port of the network position source. This is only available for network location providers.

N/A

positionSourceInfo.geoidSeparationCustom

Difference between the WGS-84 earth ellipsoid and mean sea level as defined by the user in the app settings. This is available for all location provider types.

Meters

positionSourceInfo.antennaHeight

The distance from the antenna to the ground surface is subtracted from altitude values. This is available for all location provider types.

Meters

positionSourceInfo.altitudeType

Indicates the selected altitude type. Potential results are altitude above mean sea level (0) and height above ellipsoid (1). This is available for all location provider types.

geoidSeparation

Returns the difference between the WGS-84 earth ellipsoid and mean sea level as reported by the GNSS receiver. This is also sometimes referred to as orthometric height.

Meters

accuracyType

Indicates the type of accuracy reported by the horizontalAccuracy and verticalAccuracy properties. Potential results are RMS (0) and DOP (1). RMS is root mean square accuracy. This is calculated based on 68 percent confidence interval for latitude, longitude, and altitude errors reported in the GST sentence provided by the receiver. If the receiver does not support GST, DOP is used instead. DOP is dilution of precision based accuracy. This uses a constant user estimated range error (UERE) value to estimate horizontal and vertical accuracies.

N/A

positionAccuracy

Returns the mean radial spherical error. Encompasses both horizontal and vertical error.

Meters

latitudeError

Holds the value of latitude 1-sigma error. This property will only be populated if your positioning device supports GST sentences in NMEA streams.

Meters

longitudeError

Holds the value of longitude 1-sigma error. This property will only be populated if your positioning device supports GST sentences in NMEA streams.

Meters

altitudeError

Holds the value of altitude 1-sigma error. This property will only be populated if your positioning device supports GST sentences in NMEA streams.

Meters

hdop

Returns the positional data's Horizontal Dilution of Precision (HDOP).

N/A

vdop

Returns the positional data's Vertical Dilution of Precision (VDOP).

N/A

pdop

Returns the positional data's Positional Dilution of Precision (PDOP). The equation used to determine PDOP is PDOP^2 = HDOP^2 + VDOP^2.

N/A

differentialAge

Returns the age of the differential signal and correction used by the GPS receiver to differentially correct the position.

Seconds

referenceStationId

Returns the differential reference station ID (DSID) of the station used by the GPS receiver.

N/A

satellitesVisible

Returns the amount of positioning satellites visible at the time of location capture.

N/A

satellitesInUse

Returns the amount of positioning satellites being used to return the position data.

N/A

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

Note:

If the default locator service for your ArcGIS Enterprise is the ArcGIS World Geocoder, or if the ArcGIS World Geocoder is used as the locator URL parameter as in the example above on an enterprise survey, you will receive a token error on performing a reverse geocode. To avoid this, create a proxy item that has ArcGIS Online access credentials saved in it for a user with permissions to perform geocoding. This item can then be set as either the default locator service for a portal, or the destination for a locator URL parameter in the reverse geocoding function.

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.