Include a map in a survey

Survey123 is a form-centric data collection app. The form is the first thing you see when you start a survey. A map is optional. To collect location information in a survey, add a geopoint, geotrace, or geoshape question to the survey.

The map is shown on the form as a small thumbnail, but when you click it, it expands to full screen. In full-screen mode, you can tap the map to select your location.

The Map tab in Survey123 Connect provides access to a number of defaults for maps used in a survey. This includes setting the coordinate format, zoom level, and home location. You can also set a default basemap for all map questions in a survey by clicking the Basemap button on the lower map.

Coordinate format

Survey123 can display a location value in a number of formats. A format can be provided for a survey in the Survey123 Connect map settings, which will be reflected in the display of the location. This doesn't apply when inputting a value manually, which will only accept decimal minutes. This also doesn't affect the value recorded in a survey, which will only be recorded in decimal degrees.

The following coordinate types are available:

  • Degrees Minutes
  • Decimal Degrees
  • MGRS
  • USNG
  • UTM/UPS

Home location

The home location provided for a survey will be returned if the device's location cannot be found. When using the map page of a survey, you can return to the home location by selecting the Home button Home. The Survey123 website also uses the zoom level provided for the home location as a default when either viewing or printing individual survey results.

Use an online map in a survey

The default map selected in the Survey123 Connect survey map settings will determine which online basemap will be used as a default for the survey. You can change this basemap from the default in the Survey123 field app by selecting the Basemap button on the map page of the survey.

The list of available basemaps is populated by your ArcGIS organization's shared basemaps. Other online maps can be linked to a survey. All maps used in the Survey123 field app must use the Web Mercator Auxiliary Sphere projection.

You can choose between Basic and Standard map types for the location questions in a survey. Standard is the default and is recommended for most devices. Survey123 Connect and the Survey123 field app support the following when using Standard map types:

  • Raster tile services
  • Web maps
  • Map services
  • Image services
  • Vector tile services
  • Web map services (WMS)
  • Web map tile services (WMTS)
  • Tile packages (TPK)
  • Vector tile packages (VTPK)
  • Mobile map packages (MMPK)
Note:

A default map and map gallery for all surveys in your organization can be set separately from your organization's usual defaults by an administrator on the Organization page of the Survey123 website. For more information, see Organization survey and settings management.

For devices that encounter performance issues when displaying a map, you can use Basic map types. If Basic map types are being used, you will only be able to use raster tile services and tile packages (TPK) up to 2 GB in size for offline use. Basic map types are the default on older Android and iOS devices, or you can select them manually in both the field app and Survey123 Connect by browsing to Settings > Map and selecting Basic under Map types.

When using Basic map types, the following default online basemaps are available:

  • World Street Map
  • World Imagery
  • World Topographic Map
  • USA Topographic Map
  • OpenStreetMap
  • OpenStreetMap Humanitarian

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 on loading the survey. You can alternatively set the map parameter using the map's item ID, for example, map=de26a3cf4cc9451298ea173c4b324736. You can set multiple maps in this way by separating their names or item IDs by a pair of | symbols, for example, map="World Topography"||de26a3cf4cc9451298ea173c4b324736. This will use the first map as a default, using the second map as a fallback if the app can't access the first, and then the third if the app can't access the second, and so on. This parameter can be used with any online or offline maps linked to a survey through Linked Content.

Link an online map to a survey

To make an online map available to users of a survey, the online map must be linked to the survey. You can do this in Survey123 Connect.

  1. Open the survey in Survey123 Connect.
  2. Open the Linked Content tab.
  3. Click Add Map Link. A window appears with all the map services and packages shared to your named user account.
  4. Select an online map, and click OK.

This link is instant, and the survey does not need to be republished to use. In the Survey123 field app, you can immediately browse to the full-screen map view of a question, and from the basemap selector, choose the newly linked online map.

Manually associate an online map to a survey

To use an online map in a survey, its URL must be contained in the survey's .info file. The steps above to link an online map to a survey will add this URL for you. If required, you can also manually associate an online map to a survey by editing the .info file directly. If you've already uploaded the survey to ArcGIS, you'll already have an .info file you can edit. If you haven't already uploaded the survey to ArcGIS, you can create an .info file with the following information.

To reference an online map, you must enter a tile template URL. The following are examples of tile template URLs:

  • OpenStreetMap
    http://tile.openstreetmap.org/${z}/${x}/${y}.png
  • Esri default basemap
    http://services.arcgisonline.com/ArcGIS/rest/services/World_Topo_Map/MapServer/tile/{{z}}/{{y}}/{{x}}.png
  • Esri custom basemap
    http://tiles.arcgis.com/tiles/e7dVfn25KpfE6dDd/arcgis/rest/services/MyCustomMap/MapServer/tile/${z}/${y}/${x}

The following code snippet shows the addition of an Esri default online basemap in a survey's .info file:

{
    "displayInfo": {
        "map": {
            "mapTypes": {
                "append": false,
                "includeLibrary": false,
                "mapSources": [
                    {
                        "name": "Imagery",
                        "url": "https://servicesdev.arcgisonline.com/ArcGIS/rest/services/World_Imagery/MapServer/"
                    }
                ]
            }
        }
    }
}

Use an offline map in a survey

You can use an offline map in a survey, but some preparation by the survey creator is required. Offline maps can be .tpk, .vtpk, and .mmpk files. For more information, see Prepare basemaps for offline use.