Work with data files

Just as layers in your app can use data sourced from online services, such as ArcGIS Online, WFS, or WMS services, layers can also use data from data files stored locally on your user's device. Local data files support scenarios where your users never have a network connection.

This page describes what you can do with data files and lists supported data file formats. It also provides details on how to use a data file in your app, which are summarized in the following steps:

  1. Sideload or download the data file onto your user's device.
  2. Access the data file with ArcGIS Runtime.
  3. Create a layer referencing the data file.
  4. Add the layer to a map or scene.

For information on mobile map packages and mobile scene packages, which are also stand-alone files, see Offline maps, scenes, and data or the ArcGIS Pro topics Share a mobile map package or Share a mobile scene package. For details on working with data from services while offline, see Work with offline data.

What you can do with data files

Examples of things you can do in your app using local data files include the following:

  • Display maps or scenes without a network connection.
  • Access, display, and analyze data sideloaded onto a device.
  • Include data with an application install.
  • Collect data on devices that never have access to a network connection.
  • Share datasets between applications using peer-to-peer technology.

Supported data file formats

ArcGIS Runtime supports the data files listed in the following table:

Data file typeData access APILayer APICan query?Can edit?License level
Vector tile package AGSVectorTileCacheAGSArcGISVectorTiledLayerNoNoLite
Image tile packageAGSTileCacheAGSArcGISTiledLayerNoNoLite
Mobile geodatabase

Create a .geodatabase file (SQLite database) in ArcGIS Pro or ArcMap, or by downloading offline data from a feature service.

AGSGeodatabaseAGSFeatureLayerYesYesLite
Scene layer package

For display in scenes only.

N/A

Access a Scene Layer Package (.slpk) file directly from the ArcGIS Scene Layer

AGSArcGISSceneLayerNoNoLite
ShapefileAGSShapefileFeatureTableAGSFeatureLayerYesYesStandard
Local raster file

The following raster formats are supported: ASRP/USRP, CIB, CADRG/ECRG, DTED, GeoPackage Raster, GeoTIFF/TIFF, HFA, HRE, IMG, JPEG, JPEG2000, Mosaic Dataset in SQLite, NITF, PNG, RPF, SRTM, CRF, and MrSID.

AGSRasterAGSRasterLayerNoNoStandard
OGC GeoPackage (feature data)AGSGeoPackageFeatureTableAGSFeatureLayerYesYesStandard
OGC GeoPackage (raster data)AGSGeoPackageRasterAGSRasterLayerNoNoStandard
OGC KML file (.kml file or compressed .kmz file)AGSKMLDatasetAGSKMLLayerNoYesStandard
Electronic Nautical Chart (S-57)

For display in maps only. Not supported in scenes.

AGSENCCellAGSENCLayerNoNoStandard
Other (e.g. GeoJSON)AGSFeatureCollectionAGSFeatureCollectionLayerYesYesLite

Vector tile package

Vector tiled layers contain vector representations of data across a range of scales. Unlike raster tiles, they can adapt to the resolution of their display device as you zoom in and out.

When you create a vector tile package, it must be in the same spatial reference as the map in which it will be displayed.

To create a vector tiled layer from the vector tile package (.vtpk) instantiate an object with the vector tile package's file URL. The default style loads directly from the vector tile package.

If you have copied the vector tile package file into the app's documents folder, you can instantiate a vector tiled layer with the following code:

         
1
2
3
4
5
6
7
8
9
//create a new map with vector tile package as the basemap
//
let documentPath = NSSearchPathForDirectoriesInDomains(.documentDirectory, .userDomainMask, true)[0]
let vtpkPath = "\(documentPath)/myVectorTileCache.vtpk"
//
//instantiate a vector tiled layer with the path to the vtpk file
let localVectorTiledLayer = AGSArcGISVectorTiledLayer(url: URL(fileURLWithPath: vtpkPath))
let map = AGSMap(basemap: AGSBasemap(baseLayer: localVectorTiledLayer))
mapView.map = map

Image tile package

Image tiled layers are typically used to display pregenerated tiled data as basemaps. You can take a portion of tiled data and store it within a single tile package (.tpk or .tpkx) file for completely disconnected scenarios. To store a portion of tile data as a tile package, you must specify area of interest, the tiling scheme, the levels of detail, and the tile format using one of the following approaches:

  • Run the ArcGIS Pro python tool, Create Map Tile Package, to create a tile package file.
  • In ArcMap, choose File > Share As > Tile Package to create a tile package file, as described in the ArcMap topic, How to create a tile package.
  • In ArcMap, choose Share as > ArcGIS Runtime Content to export the map's basemap layer to a tile package file (.tpk) that is output within the ArcGIS Runtime Content folder. For details, see the ArcMap topic Creating ArcGIS Runtime content, which is available with ArcGIS 10.2.1 for Desktop or later. Also see ArcMap's tile packages.

When you create a tile package, it must have the same spatial reference as the map in which it will be displayed.

Once you have the .tpk or .tpkx file, you can add it to your app using a path or using the documents folder.

Use a path

To create a tiled layer from a tile package file, instantiate an object with the path to the tile package file on the device.

Use the documents folder

If you have copied the tile package file into the app's documents folder, you can instantiate a tiled layer with the following code:

         
1
2
3
4
5
6
7
8
9
//create a new map with tile package as the basemap
//
let documentsPath = NSSearchPathForDirectoriesInDomains(.documentDirectory, .userDomainMask, true)[0]
let tpkPath = "\(documentsPath)/myTileCache.tpk"
//
//instantiate a tiledLayer with the path to the tpk file
let localTiledLayer = AGSArcGISTiledLayer(url: URL(fileURLWithPath: tpkPath))
let map = AGSMap(basemap: AGSBasemap(baseLayer: localTiledLayer))
mapView.map = map

Feature layer

Feature layers allow you to display, select, edit, and query individual features and their attributes. You can work with features offline using features stored in a data file, such as a mobile geodatabase file (.geodatabase), a GeoPackage file (.gpkg), or a shapefile (.shp). You can edit feature geometry and attributes, and, when using a mobile geodatabase, can also edit attachments and related records.

ArcGIS features

Mobile geodatabases (.geodatabase) can be created with ArcGIS Pro 2.7 or later or ArcMap 10.2.1 or later.

In ArcGIS Pro, create a mobile geodatabase using the instructions in the ArcGIS Pro help topic Create a mobile geodatabase.

In ArcMap, create a mobile geodatabase using the instructions in the ArcMap help topic Creating ArcGIS Runtime content.

The steps to create a feature layer from a mobile geodatabase are:

  1. Instantiate an AGSGeodatabase object with a path to the geodatabase file.
  2. Load the geodatabase and instantiate an AGSFeatureTable from one of the geodatabase's feature tables.
  3. Create an AGSFeatureLayer from the AGSFeatureTable and add it as an operational layer to the map.

If you have copied the geodatabase file into the app's documents folder, you can instantiate a feature layer with the following code:

                  
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
//add an offline feature layer to your map
//
let documentPath = NSSearchPathForDirectoriesInDomains(.documentDirectory, .userDomainMask, true)[0]
let geodatabasePath = "\(documentPath)/Trails.geodatabase"
//
//instantiate geodatabase with the path to the .geodatabase file
self.geodatabase = AGSGeodatabase(fileURL: URL(fileURLWithPath: geodatabasePath))
//
//load the geodatabase
self.geodatabase.load { [weak self] (error: Error?) in
 if let error = error {
  print(error)
 }
 //once loaded, instantiate the feature layer from one of the geodatabase feature tables
 let featureTable = self!.geodatabase.geodatabaseFeatureTable(withName: "Trailheads")!
 let featureLayer = AGSFeatureLayer(featureTable: featureTable)
 self?.mapView.map?.operationalLayers.add(featureLayer)
}

GeoPackage

GeoPackage is an open, standards-based, platform-independent, portable, self-describing, compact format for transferring geospatial information. It uses a single SQLite file (.gpkg) that conforms to the OGC GeoPackage standard. You can create a GeoPackage file from your own data using the Create SQLite Database tool in ArcGIS Pro.

To display features stored in a GeoPackage file, you must do the following:

  1. Instantiate an AGSGeoPackage with the .gpkg file path.
  2. Load the GeoPackage and then examine its list of AGSGeoPackageFeatureTables.
  3. Create an AGSFeatureLayer from one of the AGSGeoPackageFeatureTables and add it as an operational layer to the map.

If you have copied the geopackage file into the app's documents folder, you can instantiate a feature layer with the following code:

                   
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
//add an offline feature layer to your map
//
let documentPath = NSSearchPathForDirectoriesInDomains(.documentDirectory, .userDomainMask, true)[0]
let geopackagePath = "\(documentPath)/Trails.gpkg"
//
//instantiate geopackage with the path to the .gpkg file
self.geopackage = AGSGeoPackage(fileURL: URL(fileURLWithPath: geopackagePath))
//
//load the geopackage
self.geopackage.load { [weak self] (error: Error?) in
 if let error = error {
  print(error)
 }
 //once loaded, add the first feature layer from the geopackage to the map.
 if let geoPackageTable = self?.geoPackage?.geoPackageFeatureTables.first {
  let featureLayer = AGSFeatureLayer(featureTable: geoPackageTable)
  map.operationalLayers.add(featureLayer)
 }
}

Shapefiles

To create a feature layer from a shapefile (.shp), do the following:

  1. Instantiate an AGSShapefileFeatureTable with the path to the shapefile. This path must point to the .shp file. The .shp file's associated files (.shx and .dbf and so on) must be present at the same location.
  2. Create an AGSFeatureLayer from the AGSShapefileFeatureTable and add it as an operational layer to the map.

If you have copied the shapefiles into the app's documents folder, you can instantiate a feature layer with the following code:

             
1
2
3
4
5
6
7
8
9
10
11
12
13
//add a shapefile to your map
//
let documentPath = NSSearchPathForDirectoriesInDomains(.documentDirectory, .userDomainMask, true)[0]
let shapefilePath = "\(documentPath)/trails.shp"
//
//instantiate shapefile feature table with the path to the .shp file
let shapefileTable = AGSShapefileFeatureTable(fileURL: URL(fileURLWithPath: shapefilePath))
//
//create a feature layer for the shapefile feature table
let shapefileLayer = AGSFeatureLayer(featureTable: shapefileTable)
//
//add the layer to the map.
map.operationalLayers.add(shapefileLayer)

Raster layer

Raster data consists of a matrix of cells in which each individual cell contains a value representing information. For example, satellite or aerial images and photographs for visualizing an area. You can define renderers to display the raster data. This SDK supports several raster formats. To work offline, copy the raster data onto your device and add the raster dataset to your app using the AGSRaster class. For more information and a list of supported raster formats, See Add raster data.

Your browser is no longer supported. Please upgrade your browser for the best experience. See our browser deprecation post for more details.