Layer types

Different layer types are used to draw different data types. Generally, the layers in a map can be categorized as either basemap, operational, or graphics layers. The functionality and performance may differ, depending on the characteristics of the data and how it is accessed and displayed in an app.

See Maps and layers to learn more about choosing how to build maps from layers.

Choosing layer types

Most layers display content from GIS server web services, such as ArcGIS for Server services, Bing Maps, Open Street Map, or WMS services.

One kind of service is known as a map service. Map services fall into two broad categories: dynamic or tiled. Dynamic map services return map images created on-the-fly when requested by a client. Tiled map services provide pre-generated images based on some tiling scheme, and the layer assembles these tiles in the client app. Another kind of service is known as a feature service. ArcGIS for Server feature services return sets of features from a single layer as a response.

Other layers display different types of content. A graphics layer does not rely on a web service for its content. Specialized layers are also available for working with data sources such as Web Map Services (WMS) information, and KML.

The sections below suggest the typical classes to use for your basemap, operational, and graphics layers. However, these are not absolute rules, and the choice of class should be based on an understanding of the characteristics of each type. Some examples of exceptions are discussed in the sections below.

A wide variety of layer classes are provided by the API. Each can be used to display a specific data type, and each has its own functionality and performance characteristics. Generally, each layer class is used for a particular layer type—basemap, operational, or graphics.

The diagram below shows the major layer classes in the API and their inheritance relationships, though for simplicity not all layer classes are included (class names in italics are abstract classes).

Java layer UML diagram

Common layer properties

All layer types inherit from a common Layer class, which allows certain properties to be queried or changed for any layer type.

  • Get the layer's full extent , using the getFullExtent method.
  • Determine what spatial reference is used by the layer, using the getSpatialReference method.
  • Hide and show the layer, using the setVisible method.
  • Control how transparent or opaque a layer is, using the setOpacity method.
  • Change the visible layer's scale range thresholds , using the setMinScale and setMaxScale methods.

Basemap layers

Basemap data is typically provisioned as a tiled map layer. Different classes are used to create basemap layers, depending on the displayed data.

If your basemap must be used in maps with a wide variety of different spatial references, or changes frequently, or is used infrequently, it may be more appropriate to publish data as a dynamic map service. Additionally, if your operational data changes infrequently and is used by a large amount of users, it may be more appropriate to publish it as a tiled map service.

Tiled service layers

API classes: ArcGISTiledMapServiceLayer, BingMapsLayer, OpenStreetMapLayer, WMTSLayer—Tiled map service layers are connected to cached map services (from ArcGIS for Server, an OpenGIS Web Map Tile Service implementation, OpenStreetMap, or Bing), which provide map images at predefined scales in a tiling scheme. The tiling scheme is set by the server. The map image tiles are raster (also called bitmap) images drawn on the map view and arranged into their tiling scheme by the client API. These services can contain multiple sublayers.

Functional characteristics

Because each tile image already exists on the server, it is not possible to change the visibility of the individual layers or the service's default spatial reference of the map (they can be considered as static map services). In addition, the data cannot change over time unless the cache is refreshed. Tiled service layers cannot be queried.

Performance characteristics

Tiled map services are some of the fastest map services available in the runtime. Map images are pre-created and cached by the server, and returned from the server very quickly. Multiple images are usually returned for a single map extent. Requests are made on multiple threads and the responses are handled asynchronously (tiles are requested and drawn individually from one another). This approach results in many small requests to the server and little client-side processing to draw the returned images. The size of each returned image increases as the resolution or complexity of the images increase. For example, high-resolution imagery tiles are larger in file size than topographic mapping for the same area and map extent.

Offline tiled layers

API classes ArcGISLocalTiledLayer— A cache of tiles can be downloaded from the server to the client device and displayed as a layer in an app, without the need to remain connected to the service. The cache can be downloaded as a single Tile Package (TPK ) file, or as an ArcGIS Compact Cache, or can be created using ArcGIS for Desktop and directly provisioned to the device. Learn more about creating offline maps.

Functional and performance characteristics

Local tiled layers display even faster than tiled service layers, as no network calls are required to retrieve the image tiles. However, data must be prepared in advance by being generated and downloaded to the device over the network, or by provisioning the generated files directly to the device file storage. Other functional and performance characteristics are similar to that of tiled service layers.

Operational layers

Operational data is typically provisioned as a feature service, or as a dynamic map service. The choice of service type depends on what functionality and performance characteristics are required for the layers. If editing is required, use feature services; however, if complex rendering is required, dynamic map services may be more appropriate. More differences are highlighted below.

If your operational data does not require editing, changes infrequently, and is used by a very large amount of users, it may be more appropriate to publish it as a tiled map service. Conversely, if you have a basemap that must be used in maps with a wide variety of different spatial references, or changes frequently, or is used infrequently, it may be more appropriate to publish data as a dynamic map service.

Feature layers

Feature layers display data from feature services or from supported local data sources such as shapefiles, GeoPackages, and geodatabases. Feature layers can be used to display, select, and query features in a layer. If the underlying feature service or table supports editing, you can also use feature layers as a basis for editing geometry, attributes, and attachments.

Features in a feature layer are retrieved from a feature service as the app is used, or alternatively, are read from a feature data source stored locally on the machine. Features can also be downloaded from a sync-enabled feature service when the device is connected and cached locally for use when the device is offline. Choose from the options below (online, offline, or offline with sync) according to the workflows you want to support in your app.


API classes: GeodatabaseFeatureServiceTable, FeatureLayer—The geometry, attributes, and attachments of features from a feature service are temporarily cached in a table on the client. The feature layer uses this table to draw the features natively in the map, based on the map extent. New features are retrieved automatically when you navigate the map. Changes to features already cached in the app are not retrieved from the server table unless the layer is specifically refreshed. The local table cache is discarded when the layer is disposed.

Create and initialize a GeodatabaseFeatureServiceTable, then create a FeatureLayer by passing in the GeodatabaseFeatureServiceTable to the constructor, and add the FeatureLayer to the map. The GeodatabaseFeatureServiceTable class is a subtype of GeodatabaseFeatureTable, which is used for offline feature layers.

Feature request modesGeodatabaseFeatureServiceTable supports three different modes, which significantly affect the functionality and performance of the layer.

  • On interaction cache—The default mode for tables containing spatial features. When the table is used in a layer in a map, features are requested for the visible extent and are cached locally. Features continue to be requested and cached as you navigate the map to other extents. For extents that have already been visited, features are not requested again unless the cache has been cleared or refreshed. The API chooses the optimal way to execute a query, either querying the local cache, or querying the service and importing the results into the local cache. For example, if a spatial query is executed in the current map extent, results are obtained from the local cache—this avoids re-fetching features from the service. This mode is best for editing data that does not change frequently on the server, or if there is a large amount of data on the service. This mode is not recommended if you have an occasional or unreliable connection to the service.
  • Manual cache—The default mode for tables containing non-spatial records. The table's local cache can be populated by calling the populateFromService method of GeodatabaseFeatureServiceTable. Features are never requested, and the cache is never populated based on map interaction. Queries are executed against the local cache, with one exception—the queryRelated method is always executed against the server. This mode is recommended when the data from the service is not expected to change frequently and when it is not critical for the client app to always have the most recent changes. The amount of data populated to the local cache from the service is expected to be small.
  • On interaction no cache—When the table is used in a layer in a map, features are requested for the visible extent and are cached locally. Features are requested from the server each time you navigate the map, regardless of whether the extent has been visited before. Queries are always executed against the server. Navigating the layer and querying the table both cause the local cache to be cleared and repopulated; meaning any local edits that haven't been applied to the server are lost. This mode is recommended if it is critical for your app to always be working with the latest data. It is expected that this mode will have a higher network usage. This mode is not recommended if you have an occasional or unreliable connection to the service.

Offline, sync-enabled

API classes: GeodatabaseFeatureTable, FeatureLayer—A local cache of a feature service can be downloaded from ArcGIS for Server and displayed as a layer in your app, without the need to remain connected to the service. Features are downloaded to a local geodatabase file, using the GeodatabaseSyncTask.

Create and initialize a GeodatabaseFeatureTable, and create a FeatureLayer by passing in the GeodatabaseFeatureTable to the constructor, then add the FeatureLayer to the map. Learn more about creating offline maps.


API classes: ShapefileFeatureTable, GeopackageFeatureTable, FeatureLayer—Use a feature layer to display data from a cache of features in a shapefile (.shp) or a GeoPackage (.gpkg), stored locally on the device. A GeoPackage is a data source that conforms to the OGC GeoPackage specification (

Create a Geopackage or ShapefileFeatureTable from the path to the GeoPackage or shapefile, respectively. For a GeoPackage, retrieve a GeopackageFeatureTable from the Geopackage. To display the features in your local data source, pass the GeopackageFeatureTable or the ShapefileFeatureTable to the constructor of a FeatureLayer, then add the FeatureLayer to the map.

Functional characteristics

As the feature attribute, geometry, and any attachment information is cached locally, individual features in these layers can be queried and filtered based on spatial queries or text-based WHERE clauses. If the layer is created from an editable ArcGIS for Server feature service, the feature layer can be edited, and edits pushed to the service when required. If the layer is created from a GeoPackage data source, you can edit the features locally, but as there is no associated feature service, you cannot sync the edits with a service.

If the feature layer was originally created from a sync-enabled feature service, edits made to the features in an offline layer can be uploaded to the service, and updates from the service can be synced to the client app.

Local caches cannot be reprojected automatically, so they should be used in a map that has the same spatial reference as the local cache.

Performance characteristics

As full feature information is cached locally in a geodatabase or GeoPackage, and features are drawn natively, this layer type offers excellent performance of display when zooming and panning the map, within the extent of cached features. Querying such features is also efficient, enabling app functions such as providing real-time updates of query results in a map.

The local geodatabase cache must be initially created, which requires server-side processing time, and the download to the device may require extensive network usage and subsequent local device storage. Additionally, app memory increases with the number and complexity of the features cached. Network usage can be eliminated by provisioning the cache directly to the device in advance, by creating the cache using a desktop computer and copying it to the device internal memory (or expandable memory cards if your device supports this). This workflow may be suitable if the data is not changing too frequently.

ArcGIS feature service layers

API classes: ArcGISFeatureLayer—Feature service layers create features from a JavaScript Object Notation (JSON) response from an ArcGIS for Server feature service or map service. Each feature contains geometry and attribute information, and is drawn natively in the map.

ArcGIS feature service layers can only be used when the device remains connected; however, they do offer support for geodatabase versions and queries on related fields. Many existing apps use ArcGIS feature service layers as they were added to the API before other feature layer types.

Functional characteristics

ArcGIS feature service layers provide rich functionality, like other feature layer types, because they contain complete information about all the features displayed on the map. The individual features in these layers can be queried, selected, and filtered based on spatial queries or text-based WHERE clauses. If the layer is created from an editable ArcGIS for Server feature service, the feature layer can be edited.

Performance characteristics

The rich functionality of the feature layer comes at a slight cost in terms of request processing times by the server, response processing times, and rendering speed. This is because the information about each feature is returned by the server, parsed and processed into features on the device, and drawn onto the screen. Performance characteristics of feature service layers can be adapted by changing feature layer settings.

Understanding these issues, and applying the most appropriate settings of feature layers for your scenario, help you to maximize the performance of feature layers for your app and build exciting and functional apps.

Feature service layer settings

Changing the client-side settings of feature service layers allows you to change all aspects of the layer's performance, including the request frequency profile, response size, processing time, and rendering time. These settings are mostly located in the ArcGISFeatureLayer.Options class, but some are set on the feature layer class (remember, these need to be set after the layer has initialized).


For maximum performance, regardless of the client side settings, you should still adhere to best practices for setting up the services on the server.

Output attribute fields—The attribute fields returned from the server can be limited by setting a list of required output fields. This means that less data is sent over the network and processed in the response, as responses contain less information.

Maximum vertex offset—The complexity, and therefore in-memory size, of geometries returned from the server can be reduced by setting a maximum offset value. This value, set in map units, is used to generalize the feature vertices on the server before the information is returned. It should not be used if you're editing the feature, as some vertices will be missing and topological rules can easily be broken.

Mode—Feature service layers support three different modes, which significantly affect the functionality and performance of the layer.

  • Snapshot—Features are immediately retrieved from the server after the layer is added to the map, and are not requested again. This eliminates any need to return to the server for further information, but can become cumbersome if the layer contains a large number of features, or very a smaller number of very complex features. The device can be overwhelmed by the number of features it needs to draw, or the service can reach its limit of how many features it can return at once. The default number of features returned by ArcGIS for Server 10 is 1000, but this limit is configurable on the server for each service. Use snapshot mode only with smaller datasets.
  • On demand—Only features within the current extent of the map are retrieved from the service. As you navigate the map, the layer fetches more features for subsequent map extents. More requests to the server will be made by your app because features may be fetched every time you navigate the map. However, on demand mode has the potential to use less memory than snapshot mode, providing the map extent only requires a subset of features to be fetched from the service. It may therefore be particularly suitable for larger datasets with a lot of complex features. Sensible layer scale thresholds should be set on the service to ensure that a reasonable number of features are returned at any map scale. You can customize, to a certain degree, how many and how often features are fetched from the service by adjusting the buffer factor settings on the layer. For example, a buffer factor of 2 allows the layer to request features within an extent twice as large as the current extent. This can improve the user experience as these features are immediately visible when you pan within that buffer, without requiring additional requests. You can also set a refresh interval after which an on-demand layer should automatically refresh its features. Expired features can be retrieved automatically as soon as the expiration interval is reached, or when you next navigate the map and the cached features are refreshed. These settings can be useful if the data in the service changes frequently and you don't want the layer to display stale features.
  • Selection—Features are requested from the service only when a selection is made. Initially, no features are requested at all. This mode is useful when you only want to highlight one or more features in your app. Often, selection mode is used in a map in addition to a dynamic map service layer of the same dataset. For example, if you have a road layer with custom symbology not supported for display using a feature layer, but you want to display and perhaps allow editing on the layer, a dynamic map service layer and a feature layer in selection mode can effectively be used in conjunction. When a feature in the feature service layer is selected, this can be drawn using a simple client-side symbol. Once the edit is applied and the selection cleared, a refresh of the dynamic map service layer displays the updated road.

Feature collections—The same class used to display feature services can also be initialized to display a collection of features, either defined in a JSON string from an ArcGIS for Server Representational State Transfer (REST) API call, or created manually in code. No active service connection is required in this case. This layer can be queried in the same way as a normal feature layer, but cannot be edited using the applyEdits method.

Dynamic map service layers

API classes: ArcGISDynamicMapServiceLayer, ArcGISImageServiceLayer—A dynamic map service can contain multiple layers, rendered by the server each time a request is made, and returned to the client as a single raster image. The image does not contain any additional information about the features in the map. Dynamic map layers are connected to ArcGIS for Server dynamic map services.

Functional characteristics

Since map images are drawn by the server on every request, if your data changes, those changes are seen as soon as a new map image is requested. In addition, the visibility of individual map layers can be changed, and the data shown can be filtered by adding individual layer definition expressions. The spatial reference of this layer type can be changed from the service's default, and ArcGIS for Server re-projects each image on-the-fly to the requested output spatial reference (that of the map).

The API does not include specific methods to query individual dynamic map service layers. However, the layer's end point URL can be used by a find task, identify task, query task, or used to create a separate queryable feature layer.

Performance characteristics

For every map request, ArcGIS for Server creates a map image on-the-fly. Consequently, the server rendering time depends on the amount and complexity of the data in the map. However, if the map service is well optimized, this should result in a relatively quick response to the client, but will typically be longer than responses for an equivalent tiled map service layer. The file size of the returned map image also depends on the data in the map. As the server response is an image, this can be drawn quickly as it requires little client-side processing.

Dynamic map service layers are good candidates for showing features that change periodically over time, or that require some sort of filtering by the user, as long as the feature information (attributes, geometry, or symbol) is not required in the client. They are often used in conjunction with a feature layer in selection mode to show the latest map data without having to pull all of the feature information from the server (as with feature layers) on every map request.

Graphics layers

Graphics layers can be used to display information that is not covered by the other types of layer above. Graphics are defined in memory in your app, based on user actions, resulting from an operation, or converted from the information in an external information feed.

Feature layers share a little functionality with graphics layers. For more information about when to use feature layers versus graphics layers, see Features and graphics .

API classes: GraphicsLayer—Graphics in a graphics layer can contain geometry and attribute information, and can draw graphics using individual symbols or a layer-based renderer. Like features in a feature layer, each graphic draws natively in the map.

Functional characteristics

As a graphic contains geometry and attribute information, you can display information about the graphics. For example, you can show pop-ups for graphics in a graphics layer. You can also find graphics using screen coordinates , in response to user action events on the map. The graphics layer is responsible for drawing graphics on the map in spatial coordinates. It is not designed for drawing non-geographical marginalia such as north arrows or copyright text.

Performance characteristics

It is not recommended to add too many graphics to the graphics layer, as they are held in the device memory. If you're working with a lot of features (thousands), it may be more appropriate to put these into a feature layer, by creating a feature service.

Graphics layers are designed to best perform when graphics change location regularly, with optimal animation of the features upon zooming in and out on the map. It is possible to change the default rendering mode of a graphics layer to instead be optimized to draw greater numbers of features added to the layer in batches. Layers with the same rendering mode should be grouped together. For more information see the GraphicsLayer.RenderingMode enum.

Specialized layers

Other layer classes are available to display specific types of data in a map.

  • Group layers—Group layers are composed of a collection of other layers, and are used to represent datasets that are composed of many different layers. For example, KML layers and message group layers are both types of group layer. All group layers inherit from the GroupLayer superclass.
  • WMS—Web Map Service layers allow you to add Open Geospatial Consortium (OGC) WMS services to a map. These services are a type of dynamic map service, and may function as basemap or operational layers. The WMSDynamicMapServiceLayer is used to add WMS services to a map.
  • KML—KML files can store a wide range of geographic shapes, symbology, and attributes. They can be added to a map using the KMLLayer class, if the file is available at a publically accessible URL. KML layers are a type of group layer.
  • Message groups—Message group layers display graphics with military symbols from one of the supported symbol dictionary types. They can be added to a map using the MessageGroupLayer class, and are a type of group layer.
  • Bing maps—Bing maps services can be added as layers in a map by using the specialist BingMapsLayer class. These services are tiled map services that usually provide basemap layers for a map.
  • OpenStreetMap—Open StreetMap services can be added as layers in a map by using the specialist OpenStreetMapLayer class. These services are tiled map services that usually provide basemap layers for a map