Skip To Content

Prepare basemaps for offline use

Note:

Currently, there are many manual steps required to use basemaps in your survey. A more streamlined process is being developed for a future release. This topic will be updated as the user experience of including basemaps in your survey evolves.

Survey123 supports the use of offline basemaps. These basemaps must be of the Esri file type of tile package and use the Web Mercator Auxiliary Sphere projection. Tile packages can be created using ArcGIS Desktop.

Before generating a tile package, you must consider the data from which you will create your tile 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. The following topics provide information on preparing data for caching. In this case, your cache will be a tile package.

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

  • Copy your tile package directly to the ~\ArcGIS\My Surveys\Maps folder of your device.
  • Use your tile package from an external storage card.
  • Associate a shared tile package to a survey and download it to your device from the Survey123 field app.
  • Include the tile package in the media folder of your survey before publishing.

Create a map tile package

You can create a map tile package using ArcGIS Desktop or ArcGIS Pro. Once created, you can copy it directly to your device or external storage card for use in Survey123, 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.

Note:

Online services, such as tiled map services, are not supported in ArcGIS Desktop and ArcGIS Pro. Only maps that contain local data can be cached using the tile package tools in ArcGIS Desktop and ArcGIS Pro. Attempting to package maps that contain online services will result in a Layer type is not supported error.

To create a map tile 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 and provide the input map name, output file name, tiling format, level of detail, summary, and tags.
  3. Run the Create Map Tile Package tool.

A new .tpk 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 tile packages in ArcGIS Desktop, see How to create a tile package.

For additional details on creating tile packages in ArcGIS Pro, see Create Map Tile Package.

Note that all TPK 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:

The Survey123 field app doesn't currently support tile packages greater than 2 GB in size on 32-bit devices. If your survey needs to be used on these devices, make sure that your basemap is smaller than this limit.

Copy your tile package directly to your device

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

To copy your tile 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 iTunes or another iOS file browser app, for example, iExplorer.

  2. Copy the .tpk file to your ~\ArcGIS\My Surveys\Maps folder.

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

    When using iTunes, you will only see the ArcGIS folder and will be unable to browse lower into the folder tree. To save your TPK file to the correct location, connect your iOS device to your computer, select it in iTunes, locate Survey123 and the ArcGIS folder in the File Sharing menu, click Save To, and choose a location on your desktop. Open this new folder, open My Surveys > Maps, and paste your TPK file here. Click and drag this new folder back into the iTunes Documents list (the original location on the device) and when a message appears asking if you want to replace this folder, choose Replace. Other iOS file browsing apps (such as iExplorer) allow you to browse further into the ArcGIS folder tree and insert the TPK 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 .tpk file. For additional information on files in iTunes, refer to this Apple file sharing document.

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

    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 tile package from an external storage card

To use your tile package from an external storage card, complete the following steps:

  1. Copy your tile 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.
  3. Designate an additional map library folder 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 directly into the edit 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, tile packages on your storage card will be appended to the list of available basemaps.

Currently, no checking is performed to ensure that Map Library Folders are valid. The first path in the list will be used when you download tile packages from ArcGIS. The Map Library Folder path will not appear on iOS, as external storage is not supported on this platform.

Share your tile package

You can share a map tile 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 ArcGIS.

Tip:

The maximum file size that can be uploaded to ArcGIS via the website is 1 GB. If your .tpk file is larger than 1 GB, use the Share Package tool in ArcGIS Desktop.

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

  1. Sign in to ArcGIS Online or ArcGIS Enterprise.
  2. Browse to My Content.
  3. Click Add item.
  4. Click From My Computer.
  5. Browse to your tile package and click Add Item.
    Caution:

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

After your tile package has been uploaded to ArcGIS, be sure to copy the URL of this package's item page so it's ready to associate to a survey.

An example tile package URL is https://www.arcgis.com/home/item.html?id=4497b7bb42e543b691027840d1b9092a.

Associate a shared tile package to a survey

To make shared tile packages available to users of a survey, the download location needs to be available to the survey form. This information is stored in the survey's .info file. Currently, there is no user interface item for this, and you must type text directly into this 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 a new .info file with the following information. It is recommended that you publish your survey once to generate this file.

To associate a shared tile 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 new 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 tile package name and URL, and click 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 to 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 need to modified when associating tile packages.
  4. Republish your survey to ArcGIS.

    The following are the optional properties you can define when managing tile 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 tile package appended at the bottom. When set to false, users will only see the tile packages defined in your MySurvey.info file. The default is true.
    • includeLibrary—When you set the includeLibrary property to true, all tile 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 tile packages) defined in the MySurvey.info file will be listed. The default is true.
    • storeInMapLibrary—This is only relevant to tile package basemap sources. It specifies whether the tile package will be stored in the basemap library or if it is exclusive to the survey. If includeLibrary is set to false, tile packages are automatically stored privately, and this property will be ignored. The default is true.
  5. In Survey123, download (or redownload if you already have it on your device) your survey that now references the shared tile package.

Include your tile package in a survey

A tile package can be attached directly to a survey, so it is available with your survey immediately. To provide your tile 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 tile package, the Survey123 field app will download the .tpk file as part of the survey. The .tpk file is automatically added to the list of basemaps in the map page menu for that survey.

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

Tile Package Kreator

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

  • Create a tile package for offline use.
  • Browse and download organizational tile packages.
  • Upload existing 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. In future Survey123 releases, integration between Tile Package Kreator and Survey123 will be added.

Download Tile Package Kreator