Map expressions

Examples of report expressions for map questions are provided below.

All questions that use a map—including geopoint, geotrace, and geoshape—have common methods and parameters that you can use to modify their presentation in reports.

By default, a map in a report uses the web map that is set for the question. If the map scale is set to 0 or the parameter is omitted, the map scale is determined by the features in the map as follows:

• If there is only one point feature on the map, the map scale matches the scale set for the question.
• If there is only one line or polygon feature on the map, the map scale is determined by the extent of the feature.
• If there are multiple features on the map, the scale is determined by the extent of all features.

Map questions support setting the web map item ID and map scale as optional parameters. In the following example, a map scale of 1:100,000 is used:

${location | map:"7e2b9be8a9c94e45b7f87857d8d168d6" | mapScale:100000}

For all map questions, you can use the rotate method to define the clockwise rotation of due north in relation to the view. It accepts values from 0 to 360.

${location | map:"7e2b9be8a9c94e45b7f87857d8d168d6" | mapScale:100000 | rotate:90}

If you leave the web map item ID as an empty string, the default basemap for the question is used. If you set the map scale to 0 or omit this parameter, the map uses the default extent set for the question.

The mapExtent method can be used to explicitly set the extent of a map in a report. In the following example, a fixed map extent of Tokyo, Japan, is displayed:

${location | mapExtent:139.7:35.6:139.9:35.8:4326}

Map questions also support the size expression available for image questions. You can use this expression to control the resolution of the map displayed in the report, as shown in the following example:

${location | size:400:400}

You can use the map, mapScale, and size expressions together to provide a web map ID and map scale as well as a map image resolution, as shown in the following example:

${location | map:"7e2b9be8a9c94e45b7f87857d8d168d6" | mapScale:100000 | size:400:400}

Note:

If you're setting a map's size while using any other expression method, size must be placed last in the expression.

If the map contains a large number of records, you can use the mapFilters method to limit which records are shown. In the following example, the where parameter is used to filter a web map that has only one layer to show records with a POP2000 greater than 999999:

${location | map:"7e2b9be8a9c94e45b7f87857d8d168d6" | mapFilters:"where=POP2000>999999"}

In the following example of mapFilters, the first parameter filters the cities layer (with a layer ID of 18ece64a1fc-layer-5) to show only the first three records that have the highest population that are in the state of California. Separated from the first parameter by a colon, the second parameter filters the states layer (with a layer ID of 18ece64a1fc-layer-6) to show only the state of California:

${$map | map:"7e2b9be8a9c94e45b7f87857d8d168d6" | mapFilters:"'18ece64a1fc-layer-5':where=ST='CA'&orderByFields=POP2000 ASC&resultRecordCount=3":"'18ece64a1fc-layer-6':where=stateName='California'"}

Note:

The layer ID is a property of the feature layer object of the web map JSON.

By default, a map question displays using a default map symbol, regardless of the symbology set in the feature layer. You can use the drawingInfo method to extract and use the drawing information stored in a specific feature layer, including the symbol, label, and transparency used. You can specify this information from either the current layer or a specific feature layer through a provided URL.

${location | drawingInfo:"currentLayer"}

${location | drawingInfo:"https://.../FeatureServer/0"}

If the survey doesn't contain a map question or you're creating reports for feature layers without an associated survey, the geometry of a record can still be returned using the ${$shape} placeholder.

In a summary section, an expression for a map question displays multiple geometries in the input for a question. To include other responses for an individual report, provide a where expression with the !important tag. For more information, see Additional syntax. The following expression displays all geometries in the layer where the status field value is equal to 'broken':

${location | where:"status='broken' !important" | map:"<itemID>" | size:400:300}

Note:

In the example above, the map scale is omitted. If you set the map scale to 0 or omit the parameter, and the map contains multiple records, the map uses the combined extent for all records.

You can set the where expression to always be a true statement to ensure that every geometry in the layer is displayed:

${location | where:"1=1 !important"}

This can also be used to display all points in a repeat:

${repeat1.repeatLocation | where:"inspectionId=123 !important" | size:400:300}

The $shape keyword can also be used to return multiple map geometries:

${$shape | where:"1=1 !important" | drawingInfo:"currentLayer" | size:400:300}

The $map keyword can be used to print a map that does not reference a survey question:

${$map | map:"7e2b9be8a9c94e45b7f87857d8d168d6" | mapScale:100000 | size:400:400}

Geopoint

For geopoint questions, you can use expressions to display the latitude or longitude values from the question, as follows:

${location | getValue:"x"}

${location | getValue:"y"}

You cannot display both values with one expression; if both values are needed, you must use both expressions.

Tip:

You can also display the altitude value through a similar expression but only if the underlying feature layer supports z-values:

${location | getValue:"z"}

By default, latitude, longitude, and altitude values return the original value provided in the survey response, without truncation. As these values can often be much longer than needed in a report, consider using the round or toFixed expressions to round the value to a specific decimal place:

${location | getValue:"x" | round:3}

${location | getValue:"x" | toFixed:3}

By default, these values are output to the spatial reference used by the survey's feature layer. You can set a different spatial reference as an additional parameter by providing its WKID:

${location | getValue:"x":4326}

Geotrace and geoshape

For geotrace and geoshape questions, you can use the getValue expression to display the length of the line or the perimeter of the polygon, respectively:

${polyline1 | getValue:"length":"meters":"planar"}

For geoshape questions, you can also use the getValue expression to display the area of the polygon:

${polygon1 | getValue:"area":"hectares":"geodesic"}

The units and calculation method are optional parameters. The following units are accepted for length:

• feet
• kilometers
• meters
• miles
• nautical-miles
• yards

The following units are accepted for area:

• acres
• hectares
• square-miles
• square-kilometers
• square-meters
• square-feet
• square-yards

Alternatively, you can use any of the esriSRUnitType constants or esriSRUnit2Type constants supported by ArcGIS REST API. In the expression, use the numeric code for the constant without quotes, as follows:

${polyline1 | getValue:"length":109002:"geodesic"}

If no units are specified, the default is kilometers for length and square-kilometers for area.

The method can be either geodesic or planar. If no method is specified, geodesic is used by default.