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.

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

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

When using the Standard map type, you can download tile packages (TPK), vector tile packages (VTPK), and mobile map packages (MMPK) files. When using the Basic map type, only TPK files can be downloaded.

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 also must 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 Tips and best practices for map caches, or Best practices for using layers in maps.

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

  • 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. Select the Basemap button and choose the basemap that is located on your device to display it.

Create a map package on the desktop

You can create a map package using ArcGIS Desktop or ArcGIS Pro. Once 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 to do this 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 new map in ArcGIS Desktop or ArcGIS Pro.

    Ensure your map has a suitable name and description. To edit these, 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 your chosen tool.

A .tpk, .vtpk, or .mmpk file is created in your chosen 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 with others.

For additional details on creating map packages in ArcGIS Pro, see its documentation on tile packages, vector tile packages, and mobile map packages.

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

Create a map package in ArcGIS Online or ArcGIS Enterprise

Map packages can also be created in ArcGIS Online or ArcGIS Enterprise by creating map areas for web maps. For more information, see Create, edit, and manage map areas for ArcGIS Online or Create, edit, and manage map areas for ArcGIS Enterprise.

Note:

Only the basemaps from a map area can be used in the Survey123 field app. Each basemap layer can be downloaded as a separate offline map package. Operational layers and labels in the map area are not be displayed.

Share your map package

You can share a map package in ArcGIS so that you can download it on different devices, or share it with other people to use. 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.
Caution:

Do not check the Publish this file as a hosted layer check box when uploading your map package.

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. This can be done in Survey123 Connect.

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

    This opens a window with all map services and packages shared to your named user account. Be aware that 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 your map package in a survey

A map package can be attached directly to a survey so it is available with your 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 will download 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 your map package directly to your device

If you do not have an internet connection or are unable to connect to ArcGIS, you can copy your map package directly to your device, or use it from an external storage card.

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

  1. Connect to your device.

    If you're using an iOS device, you'll need to 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 .tpk, .vtpk, or .mmpk file to your ~\ArcGIS\My Surveys\Maps folder.

    For example, on Windows, this is C:\Users\UserName\ArcGIS\My Surveys\Maps.

    When using an iOS file browser, you will only see the ArcGIS folder and will be unable to browse lower into the folder tree. To save your map package file to the correct location, connect your iOS device to your computer, select it in your file explorer, locate the Survey123 field app and the ArcGIS folder in the File Sharing menu, select Save To, and choose a location on your desktop. Open this new folder, open My Surveys > Maps, and paste your map package file here. Select and drag this new folder back into the file explorer Documents list (the original location on the device) and when a message appears asking if you want to replace this folder, choose Replace. Some iOS file browsing apps allow you to browse further into the ArcGIS folder tree and insert the map package file directly. If you haven't previously downloaded an associated map to your iOS device, the Maps folder may not already exist. You can safely create this folder before copying your file.

  3. In the Survey123 field app, select Menu > Settings > Map and browse to your ~\ArcGIS\My Surveys\Maps folder under Map library.

    Any survey that has includeLibrary set to true (for additional details, see the last section in this topic) will now include any maps stored in this folder in the list of available maps.

Use your map package from 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 My Surveys menu, choose Settings > Map.
  3. Designate an additional map library that represents your storage card.

    The default path of ~/ArcGIS/My Surveys/Maps will already appear. You can add additional 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 selected will be 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 will be 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 will be used when you download map packages from ArcGIS. The map library folder path will not appear on iOS, as external storage is not supported on this platform.

Manually associate a shared map package to a survey

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. 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. It is recommended that you publish your survey once to generate this file.

To associate a shared map package to your survey, complete the following steps:

  1. Browse to your survey folder on your computer.
  2. Open the MySurvey.info file in a text editor.

    If you haven't already uploaded this survey to ArcGIS, this file will not exist. You can create a file called MySurvey.info, where MySurvey is the name of your survey. If the file does already exist, when editing this file in the text editor, ensure that Survey123 Connect is closed. If Survey123 Connect is open, you may lose your edits when you close the text editor.

  3. Copy the following code snippet into this file, modifying the map sources section with your own shared map package name and URL, and select Save. This snippet should be placed within the first layer of brackets in MySurvey.info.

    "displayInfo": {
            "map": {
                "mapTypes": {
                    "append": false,
                    "includeLibrary": false,
                    "mapSources": [
                        {
                            "name": "Imagery Basemap",
                            "url": "http://www.arcgis.com/home/item.html?id=4497b7bb42e543b691027840d1b9092a",
                            "storeInMapLibrary": false
                        }
                    ]
                }
            }
        },

    Your MySurvey.info file contents should now look something like this (note that your information under serviceInfo will be different):

    {
        "displayInfo": {
            "map": {
                "mapTypes": {
                    "append": false,
                    "includeLibrary": false,
                    "mapSources": [
                        {
                            "name": "Imagery Basemap",
                            "url": "http://www.arcgis.com/home/item.html?id=4497b7bb42e543b691027840d1b9092a",
                            "storeInMapLibrary": false
                        }
                    ]
                }
            }
        },
        "serviceInfo": {
            "itemId": "7a0c8f6025ad4801b684a19682d6d037",
            "type": "Feature Service",
            "url": "http://services.arcgis.com/FQD0rKU8X5sAQfh8/arcgis/rest/services/service_922426e4ec964f26abf82c20ec8dd988/FeatureServer"
        }
    }

    It is critical that you ensure the syntax in this file is correct. It is recommended that you use a JSON validator tool to confirm this. An online example is JSONLint. Other properties can exist in your .info file, but only properties of displayInfo must be modified when associating map packages.
  4. Republish your survey to ArcGIS.

    The following are the optional properties you can define when managing map packages in your surveys:

    • append—When you set the append property to true, the user will see the list of default online basemaps with your map package appended at the bottom. When set to false, users will only see the map packages defined in your MySurvey.info file. The default is true.
    • includeLibrary—When you set the includeLibrary property to true, all map packages stored on the device will appear in the list of basemaps of the current survey. When set to false, only the basemaps (online or map packages) defined in the MySurvey.info file will be listed. The default is true.
    • storeInMapLibrary—This is only relevant to map package basemap sources. It specifies whether the map package will be stored in the basemap library or if it is exclusive to the survey. If includeLibrary is set to false, map packages are automatically stored privately, and this property will be ignored. The default is true.
  5. In the Survey123 field app, download (or redownload if you already have it on your device) your survey that now references the shared map package.

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