Geotrace and geoshape questions allow you to capture a polyline or polygon on a map. You can use this geometry for the resulting feature in the feature layer instead of a point.
Unlike geopoint questions or location capture without a location question, geotrace and geoshape questions don't use device location to fill a response, although they do use your device location to center the map.
If a geotrace or geoshape question is left unanswered and its geometry is not created from a default or expression, the survey record is submitted to the feature layer with null geometry.
Note:
You can add multiple geopoint, geotrace, or geoshape questions to a survey; however, you can use only one of them as the geometry of the survey record. You can use multiple map questions if all but one question has bind::esri:fieldType set to null.
Each repeat in a survey can also have more than one geopoint, geotrace, or geoshape question; however, you can use only one of them as the geometry of a repeat record. You can use multiple map questions with the same method described above.
When capturing geotrace or geoshape questions using a map, not all features of the Survey123 field app are supported in the web app. The following features are supported in the Survey123 field app but not in the web app:
- Offline basemaps
- Style options provided for geotrace and geoshape questions
- Calculations for geotrace and geoshape questions, including the sum() function
- Location accuracy thresholds and location quality expressions
Capture methods
Geotrace and geoshape data have two capture methods, sketch and vertex. Sketch is used by default for surveys created from scratch, and vertex is used by default for surveys created from an existing feature layer. You can set a different capture method in the survey by entering method=sketch or method=vertex in the body::esri:style column for the question.
Sketch
The sketch method captures the geometry in a single motion, with the capture completing once the user has stopped drawing this single line.
For more information on how to use this method, see Sketch.
Vertex
The vertex method allows more precise geometric capture of a line or shape by placing vertices that connect together.
For more information on how to use this method, see Vertex.
The following are parameters that control behavior when capturing vertices:
- beep or nobeep—When beep is set, audible feedback is given each time a vertex is captured. When this parameter is not included, the default is nobeep.
- haptic or nohaptic—When haptic is set, haptic feedback is given each time a vertex is captured. This is supported only on hardware that supports haptic feedback. When this parameter is not included, the default is nohaptic.
- edit or noedit—When noedit is set, users can only capture vertices at their current location, undo each vertex placement, and replace the entire line or polygon. Users cannot edit an individual vertex. When this parameter is not included, the default is edit.
- streaming or nostreaming—Line or polygon vertices can be streamed as you move around. When this parameter is not included, the default is nostreaming.
The following example sets the capture method to vertex streaming with audible feedback:
method=vertex,streaming,beep
The survey author can configure the distance between adjacent, streamed vertices. By default, vertices are captured every 10 meters, but this can be modified using the distanceThreshold parameter. This parameter is separated by a space in the body::esri:style column. Other parameters that define the line or shape color can also be included.
The following example captures vertices every 25 meters and creates a red line:
method=vertex,streaming,beep distanceThreshold=25 lineColor=red
If position accuracy is important for the captured vertices, entering an accuracy threshold value in the body::accuracyThreshold column of the geotrace or geoshape question prevents vertices from being captured unless the threshold condition is met.
Defaults and expressions
You can set default geometry for a geotrace or geoshape question or use an expression to create the geometry using the results of other questions. Individual vertices that make up the answer to a geotrace or geoshape question are space-separated sets of latitude and longitude values (in decimal degrees) separated by a semicolon. To populate the answer of a geotrace or geoshape question, you must adhere to this structure to produce a valid answer. To get precise locations, these values may need to be large. For example, the following values provided in the default column of a geoshape question draw the shape around a park in Melbourne, Australia:
-37.842156723211474 144.95942945338243; -37.83554486071995 144.9726235713864; -37.85681405373047 144.98240735651922; -37.85954045531896 144.97715349053766
Tip:
Location defaults in the southern hemisphere cause an error in Microsoft Excel, as the value is read as a formula because it begins with a minus sign (-). In these cases, enter an apostrophe before the first value, and it will be read as intended in Excel. Adding an apostrophe causes no change in behavior in Survey123.
Because you can't insert these values directly when populating from select_one questions, it's recommended that you use the substr() function in the calculation column to help construct a valid answer. For example, the name of an answer in a select_one question can be the following:
+059.38330_+018.66300
This answer uses a fixed number of characters for both latitude and longitude, including zeros that would normally be truncated and an underscore placed between the two values, as spaces are not permitted in the name column. This creates a value that can be deconstructed with the substr() function to populate the following example of a geotrace question with two vertices:
substr(${previous_question1}, 0, 10) + " " + substr(${previous_question1}, -10) + "; " + substr(${previous_question2}, 0, 10) + " " + substr(${previous_question2}, -10)
This example takes the first 10 characters of two different values (the latitudes) and the last 10 characters (the longitudes) and presents them with a space separating the latitudes and longitudes, and a semicolon separating the valid locations, to produce a valid geotrace result.
You can also use the sum() aggregate function to collate a number of geopoint values in a repeat to use them as vertices for a resulting geotrace or geoshape. This allows users to capture location metadata for every vertex of the geometry. For more information, see Aggregate functions.
While a location is not immediately captured by a geotrace or geoshape question, the device location is used to center the map when loading the survey. To prevent this, set the default value as null. It will instead display options to enable location capture, load the map page for manually setting a location, or refresh a calculation if there is a calculation applied to the question.
Geosearch
Geotrace and geoshape questions include geosearch functionality, allowing users to search for an address or point of interest and have the map zoom to and place a vertex at this location.
By default, the geosearch functionality returns results from the entire world, using the ArcGIS World Geocoding Service to search for the addresses.
Note:
Geocoding using the ArcGIS World Geocoding Service will consume credits. For more information, see Understand credits.To set a specific locator to return results from, supply the locator's item ID in the bind::esri:parameters column, for example, geocode=36ff9e8c13e042a58cfce4ad87f55d19. A locator used in an ArcGIS Online survey must be an item in ArcGIS Online. A locator used in an ArcGIS Enterprise survey must be an item in the same portal as the survey.
Geometric attributes
You can use geotrace and geoshape questions in calculations to display and record geometry attributes such as length (for geotrace) and perimeter and area (for geoshape). The distance() and area() functions are used to build an expression with the geotrace or geoshape question. The distance() function returns a result in meters, and the area() function returns a result in square meters. See the geotrace and geoshape sample in Survey123 Connect for examples of calculations that convert these results into other units.
Geometry symbology
You can add styling for geotrace and geoshape questions that display in the survey. You can set this styling using the following parameters in the body::esri:style column of geotrace and geoshape questions:
- lineColor
- lineWidth
- fillColor
Colors can be specified by standard HTML color names or hex color codes. You can use eight-character hex color codes to set opacity. Multiple parameters are separated by a space, for example, lineColor=Black fillColor=#800000FF lineWidth=3.
Note:
The lineColor and lineWidth parameters are supported by both geotrace and geoshape questions. The fillColor parameter is only supported by geoshape questions.
These style options only display in Survey123 Connect and the Survey123 field app.
Point locations from the first geopoint question in a repeat can be displayed on any map in the survey. For more information, see Point overlays on maps.
Question style
You can configure the basemap, map tools, and question height for map questions.
A default basemap can be set for individual map questions using the map parameter in the body::esri:style column. For example, map="World Topography" will set the map question to use the World Topography basemap. You can also set the map parameter using the map's item ID, for example, map=de26a3cf4cc9451298ea173c4b324736. This parameter supports online and offline maps, including your own web maps. For more information, see Include a map in a survey.
The body::esri:style column accepts a mapTools parameter to control the map tools that are available for map questions. If no map tool parameter is set, all tools will be displayed. The following values are accepted:
- mapTools=search
- mapTools=mapSwitcher
- mapTools=zoom
- mapTools=home
- mapTools=locate
Multiple tools can be set by separating each value with a comma, for example, mapTools=search,locate.
The body::esri:style column accepts a height parameter for map questions.
You can set the height for a question by supplying the height parameter with a number and, optionally, a unit. The default unit is lines, referring to the height of the current input text font. For example, height=5 causes any of these questions to display five lines tall.
Alternatively, you can set the unit to a percentage of the screen height, or by number of pixels, by adding them as a suffix to the value without a space. For example, the following values are all accepted:
- height=5
- height=5lines
- height=25%
- height=250pixels
Height and map tools can be set with a space between them, for example, height=25% mapTools=search,zoom.