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 on the map to select your location.

The Map tab within the Survey123 Connect survey Settings tab 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 different 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 Home button. 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.

The following default online basemaps are available:

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

Other online maps can be used in Survey123 but must be manually associated to a survey.


This functionality is in beta. This means that documentation is incomplete, and functionality may undergo minor changes.

By default, an online map must contain tile layers. To use additional types of layers, you must enable standard map types. This can be selected in either Survey123 Connect and the Survey123 field app by opening Settings > Map and selecting Standard. The Standard map types support the following:

  • Raster tile services
  • Web maps
  • Map services
  • Image services
  • Vector tile services
  • Web map services (WMS)
  • Web map tile services (WMTS)
  • Tile packages (TPK), no size limit
  • Vector tile packages (VTPK)
  • Mobile map packages (MMPK)

A new default basemap can be set for individual map questions by setting one 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. This parameter can be used with any online or offline maps available to your survey.

Link an online map to your survey

To make an online map available to users of a survey, the online map needs to 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, under Settings.
  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 files, with an option to use expanded map types such as .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.