Geotrace and geoshape

Geotrace and geoshape questions allow you to capture a polyline or polygon on a map, using this geometry for the resulting feature in your feature layer instead of a point.

Response to a geoshape question

Unlike geopoint questions or location capture without a location question, geotrace and geoshape questions don't use device location to fill in your response, although they do use your device location to center your map.

If a geotrace or geoshape question is left unanswered and does not have its geometry created from a default or expression, the survey record will be submitted to the feature layer with null geometry.

Note:

You can add multiple geopoint, geotrace, or geoshape questions to a survey, however, only one of these can be used as the geometry of the survey record. Multiple map questions can be used 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, only one of these can be used as the geometry of a repeat record. Multiple map questions can be used with the same method described above.

Capture methods

Geotrace and geoshape have two capture methods, Sketch and Vertex. Sketch is used by default for surveys created from scratch, while Vertex is used by default for surveys created from an existing feature layer. You can set a different default in the survey by entering method=sketch or method=vertex in the body::esri:style column for your question. The user responding to your survey in either the Survey123 field app or the Survey123 web app will be unable to choose between the two.

The Sketch method is used to capture the geometry in a single motion, with the capture completing once the user has stopped drawing this single line. To begin capturing Sketch geometry, tap the Sketch button Sketch Geotrace Sketch Geoshape in the lower left of the map page and tap the map. When you have finished sketching the geometry, stop tapping the map. The geometry is then complete, with the geoshape connecting the beginning and end of the shape if necessary. The length of a geotrace, or the area and perimeter for a geoshape, is displayed below the map.

The Sketch method also provides a smart shape option, which attempts to simplify your sketched geometry into an ellipse, rectangle, or triangle. To use smart sketching, tap the Smart Shape button Smart Shapes in the lower left corner of the map page, and tap the map to begin sketching. If your sketch is recognizable as an ellipse, rectangle, or triangle, the app automatically converts it. If your sketch doesn't resemble one of these shapes, no geometry is drawn.

Once your geometry has been drawn, either tap the Confirm button to accept this geometry and move back to your survey, or tap one of the buttons in the lower left again to erase this geometry and draw another.

Response to a geotrace question

The Vertex method allows more precise geometric capture of a line or shape by placing vertices that connect together. To begin capturing Vertex geometry, tap the Vertex button Vertex Geotrace Vertex Geoshape in the lower left of the map page and tap the map to place your first vertex. More vertices can be placed by tapping the map again or tapping the Capture Vertex at Location button Vertex from Location to place a vertex at your device's location. To move the map instead of placing vertices, tap the Pan and Zoom button Pan and Zoom to change map interactions to navigation mode. You can then capture a vertex at the map's central point with the Capture Vertex at Crosshair button Vertex from Crosshair. If at any point you place a vertex at the wrong position, tap the Undo button Undo in the lower right to remove the last vertex placed, drag the point to move it to a new location, or drag the point to the Delete button that appears in the upper left of the map window. When you're done, you can tap the Confirm button to accept this geometry and move back to your survey.

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. To create these expressions, you first have to understand that 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 need to adhere to this structure to produce a valid answer. Be aware that 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 will 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 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. Adding apostrophes causes no changes 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 could 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 safely 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.

Geometric attributes

Geotrace and geoshape questions can also be used 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.

Style options

You can add styling for geotrace and geoshape questions that will display in the survey. This styling can be set using the following parameters in the body::esri:style column of your geotrace and geoshape questions:

  • lineColor
  • lineWidth
  • fillColor

Colors may be specified by either standard color names (for example, lineColor=red) or hexadecimal color code (for example, lineColor=#AARRGGBB). 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. The fillColor parameter is only supported by geoshape.

These style options will only display in Survey123 Connect and the Survey123 field app.