Include a map in your survey

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

The map is shown on your 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 your survey. This includes setting the coordinate format, zoom level, and home location. You can also set a default basemap for all map questions in your 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 your survey, which will only be recorded in decimal degrees.

The following coordinate types are available:

  • Degrees Minutes
  • Decimal Degrees
  • MGRS
  • USNG

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 your survey, the home location can be returned to 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 your 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. This basemap can be changed from the default in the Survey123 field app by selecting the Basemap button on the map page of the survey.

There are two map types: Basic and Standard. The map type can be selected in the Settings > Map tab in the Survey123 Connect and Survey123 field app main menu.

When using the Standard map type, the list of available basemaps is populated by your ArcGIS organization's shared basemaps. Other online maps can be linked to a survey. Survey123 supports the following 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)

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 settings.

When using the Basic map type, 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, 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 your survey through Linked Content.

Link an online map to your survey

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

  1. Open your survey in Survey123 Connect.
  2. Open the Linked Content tab.
  3. Click Add Map Link. This opens a window with all the map services and packages shared to your named user account.
  4. Select your preferred 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 your newly linked online map.

Manually associate an online map to your survey

To use your online map in your survey, its URL must be contained in the survey's .info file. The steps to link an online map to your survey above will add this URL for you. If required, you can also manually associate an online map to your survey by editing the .info file directly. If you've already uploaded your survey to ArcGIS, you'll already have an .info file you can edit. If you haven't already uploaded your 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:

  • Open street map—${z}/${x}/${y}.png
  • Esri default basemap—{{z}}/{{y}}/{{x}}.png
  • Esri custom basemap—${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": ""

For more details on how to edit a survey's .info file, see Prepare basemaps for offline use.

Use an offline map in your survey

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

  • Download a map package file with your survey—Link your survey to a map package file found online. When you open your survey, you'll have the option to download the map package file.
  • Include a basemap in the media folder in your survey's content folder before publishing it. When you open your survey in the Survey123 field app, the map package file will be available in your list of basemaps. No additional configuration is required.
  • Sideload a map package file—Copy a map package file to the ~/ArcGIS/My Surveys/Maps folder to make it available to any survey.
  • Browse to an existing map package file—You can use any map package file that has already been downloaded to your device in your survey. Before opening your survey, ensure that your Map Library Folder is defined. In the Survey123 field app Menu, select Settings, select the Map tab, and select the folder where your maps are saved. Then, in your survey, select your map question to display the full map page. In the map Menu, choose the basemap that is located on your device to display it.