Prepare basemaps for offline use


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. You can select the map type in the Map tab in Survey123 Connect and the Survey123 field app.

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

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


    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

You can also create map packages 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.


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.

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.

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

    This opens a window 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 your map package in a survey

You can attach a map package 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 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.

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 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 .tpk, .vtpk, or .mmpk file to your maps folder in the following location:
    • WindowsC:\Users\<username>\ArcGIS\My Surveys\Maps
    • macOS and UbuntuHome/ArcGIS/My Surveys/Maps
    • iOSSurvey123/Documents/ArcGIS/My Surveys/Maps
    • AndroidAndroid/data/com.esri.survey123/files/ArcGIS/My Surveys/Maps
  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.

    Starting with Survey123 version 3.12, when a map package is stored on an SD card for use on Android devices, the file must by copied to the location SD CARD/Android/data/com.esri.survey123/files.

  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 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 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. The map library folder path does 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 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, 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

    "displayInfo": {
            "map": {
                "mapTypes": {
                    "append": false,
                    "includeLibrary": false,
                    "mapSources": [
                            "name": "Imagery Basemap",
                            "url": "",
                            "storeInMapLibrary": false

    Your 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": "",
                            "storeInMapLibrary": false
        "serviceInfo": {
            "itemId": "7a0c8f6025ad4801b684a19682d6d037",
            "type": "Feature Service",
            "url": ""

    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 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 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 for macOS, Windows, or Ubuntu. For more information see this user guide.