Prepare basemaps for offline use

Note:

This functionality is only available for the Survey123 field app. Offline basemaps are not available for the Survey123 web app.

If the field app user opens a survey while the device is offline and no offline map has been configured by the survey author, the Esri default offline map will be visible. This default offline map is a lightweight simplified basemap of the world, designed to provide basic geographic context to local data.

Survey123 supports the use of offline basemaps. These basemaps must be of a supported Esri file type and use the Web Mercator Auxiliary Sphere projection.

You can choose between Basic and Standard map types for the location questions in surveys. 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 (TPKX or TPK)
• Vector tile packages (VTPK)
• Mobile map packages (MMPK)

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

Before generating an offline map package, you must consider the data from which you will create your map package. You can use your own data layers, Esri basemaps, or a combination of both. You must also consider the geographical extent of the area you need to cover and the scale of detail that you need to see. For more information, see Best practices for tile caches or Best practices for using hosted layers in maps.

To create and share an offline basemap for use in the Survey123 field app, do any of the following:

• Create a map package on the desktop using ArcGIS Desktop or ArcGIS Pro.
• Create a map package in a browser using ArcGIS Online or ArcGIS Enterprise.
• Create a map package in Tile Package Kreator, a dedicated desktop tool for creating TPKs.
• Share your map package for use by others in their surveys.

To get an offline basemap onto your device for use in the Survey123 field app, do any of the following:

• Link a shared map package to a survey—When you open your survey, you'll have the option to download the map package file.
• Include your map package in a survey—Include a basemap in the media folder in your survey's content folder before publishing it. No additional configuration or optional downloading is required.
• Copy your map package directly to your device—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—Browse to map package files that have been loaded to the device outside of Survey123.

Note:

The recommended way to associate an offline map with a survey is to link a shared map package, but if required, you can also manually associate a shared map package to a survey by editing the survey's .info file.

Manual association of a shared map package is useful when you need to make the map package associated with a survey accessible by the following:

• Other surveys
• The location sharing map
• The location status map

Create a map package on the desktop

You can create a map package using ArcGIS Desktop or ArcGIS Pro. Once it's created, you can copy it directly to your device or external storage card for use in the Survey123 field app, or share it in ArcGIS Online or ArcGIS Enterprise for association with surveys and for others to use. While ArcGIS Pro and ArcGIS Desktop are different applications, the process is the same for both.

To create a map package in ArcGIS Desktop or ArcGIS Pro, complete the following steps:

1. Open an existing map or create a map in ArcGIS Desktop or ArcGIS Pro.

   Ensure your map has a suitable name and description. To edit the name and description, right-click the map in the table of contents and click Properties. In ArcGIS Desktop, the Properties option can be found in the File menu.

   Tip:

   Your map must use the Web Mercator Auxiliary Sphere projection.

2. In Toolbox, choose or search for the Create Map Tile Package tool, Create Vector Tile Package tool, or Create Mobile Map Package tool, and provide the input map name, output file name, tiling format, level of detail, summary, and tags.
3. Run the tool you want to use.

A .tpkx, .tpk, .vtpk, or .mmpk file is created in the specified output location. To use this file in the Survey123 field app, you can manually copy it to your device or upload it to ArcGIS Online or ArcGIS Enterprise, where it can be shared.

All map package files are of specific areas and ranges of detail; this sample .tpk file, for example, is of a specific section of the San Bernardino Mountains in California. It has no data beyond this location and would not be useful in a survey for another area.

Note:

In ArcGIS Pro, you can make a map package of web feature layers and web tile layers within the map extent by clicking Download Map on the Map tab on the ribbon. For more information, see Take a map offline.

For additional details on creating map packages of different types in ArcGIS Pro, see the ArcGIS Pro documentation on tile packages, vector tile packages, and mobile map packages.

Create a map package in a browser

You can also create map packages in ArcGIS Online or ArcGIS Enterprise by creating map areas for web maps. For more information, see Create and manage offline map areas prepared ahead of time for ArcGIS Online or Create and manage offline map areas prepared ahead of time for ArcGIS Enterprise.

Note:

You can only use the basemaps from a map area in the Survey123 field app. You can download each basemap layer as a separate offline map package. Operational layers and labels in the map area are not displayed.

Create a map package in Tile Package Kreator

Tile Package Kreator is a desktop app for raster tile package creation and discovery. This app allows you to do the following:

• Create a raster tile package for offline use.
• Browse and download organizational raster tile packages.
• Upload existing raster tile packages to ArcGIS for sharing in your organization.

Tile Package Kreator provides an alternative method to create and manage the basemap files you need to use Survey123 offline.

Download Tile Package Kreator for macOS, Windows, or Ubuntu. For more information, see the Tile Package Kreator Features Guide.

Share a map package

You can share a map package in ArcGIS so that you can download it on different devices, or share it. Sharing can be done from ArcGIS Desktop or ArcGIS Pro, or directly in your ArcGIS organization.

To share a map package in ArcGIS, complete the following steps:

1. Sign in to ArcGIS Online or ArcGIS Enterprise.
2. Browse to My Content.
3. Select Add item.
4. Select From My Computer.
5. Browse to your map package and select Add Item.

Note:

When uploading your map package, the Publish this file as a hosted layer check box will be checked by default. This is not required when sharing a map package for use in Survey123.

Link a shared map package to a survey

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

1. Open your survey in Survey123 Connect.
2. Open the Linked Content tab.
3. Select Add Map Link.

   A window appears with all map services and packages shared to your named user account. Not all of these items can be used offline.

4. Select your preferred shared map package, and select OK.

Your map package can now be downloaded when using your survey in the Survey123 field app. For more information, see Use offline basemaps.

Include a map package in a survey

You can attach a map package directly to a survey so it is available with the survey immediately. To provide your map package with your survey, add it to the media folder in your survey's content folder before publishing.

Once a survey has been published with an attached map package, the Survey123 field app downloads the file as part of the survey. The file is automatically added to the list of basemaps available through the Basemap button for that survey.

Note:

Including your map package can significantly slow the process of uploading and downloading your survey, especially with a large map package. Because this also makes the file a required part of your survey's download, it may not be ideal for all surveys.

Copy a map package directly to a device

If you do not have an internet connection or are unable to connect to ArcGIS, you can copy a map package directly to a device.

To copy a map package directly to a device, complete the following steps:

1. Connect to your device.

   If you're using an iOS device, you must use an iOS file browser app. On macOS version 10.15 Catalina or later, you can use Finder as a file browser. On earlier versions of macOS, or on Windows, you can use iTunes or another file browser app.

2. Copy the .tpkx, .tpk, .vtpk, or .mmpk file to your maps folder in the following location:
   • Windows—C:\Users\<username>\ArcGIS\My Surveys\Maps
   • iOS—Survey123/Documents/ArcGIS/My Surveys/Maps
   • Android—Android/data/com.esri.survey123/files/ArcGIS/My Surveys/Maps
   • Android SD card—SD CARD/Android/data/com.esri.survey123/files
3. In the Survey123 field app, select Menu > Settings > Map and browse to your ArcGIS/My Surveys/Maps folder under Map library.

   By default, all maps in this folder are displayed in the list of available maps for a survey. To limit which offline maps are available for a survey, you can set includeLibrary to false in the survey's .info file. For more information, see Manually associate a shared map package to a survey.

   If location sharing is enabled for your organization, the maps added to this folder will also be available in the location sharing map.

Browse to an existing map package file

Note:

This is not possible on iOS and Android devices, as these operating systems do not allow accessing data in locations outside of the app storage. The data must be copied into the designated app storage location.

You can use a 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 add the path to the folder where your maps are saved. Then, in your survey, select your map question to display the full map page. Select the Basemap button and choose the basemap that is located on your device to display it.

A common example of browsing to an existing map package file is when you want to preload an external storage card. To use your map package from an external storage card, complete the following steps:

1. Copy your map package to your storage card and place the card in your device.
2. Start the Survey123 field app on your device, and on the menu in the upper right, choose Settings > Map.
3. Designate an additional map library that represents your storage card.

   The default path of ArcGIS/My Surveys/Maps already appears. You can add more paths by doing either of the following:

   • Type the additional path in the text box (use a semicolon to separate paths).
   • Use the folder browser to select an additional path. Any path you select is appended to your map library folder.

When you next open a survey that has the map append property set to true, map packages on your storage card are appended to the list of available basemaps.

No checking is performed to ensure that map library folders are valid. The first path in the list is used when you download map packages from ArcGIS.