Skip To Content ArcGIS for Developers Sign In Dashboard

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.

Common layer properties

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

  • Get the layer's full extent , using the fullEnvelope property.
  • Determine what spatial reference is used by the layer, using the spatialReference method.
  • Hide and show the layer, using the visible property.
  • Control how transparent or opaque a layer is, using the opacity properties.
  • Change the visible layer's scale range thresholds , using the minScale and maxScale properties.

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: AGSTiledMapServiceLayer, AGSBingMapLayer, AGSOpenStreetMapLayer, AGSWebTiledLayer, AGSWMTSLayer—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 AGSLocalTiledLayer— 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. Feature layers can be used to display, select, and query features in a layer. Use feature layers to edit geometry, attributes, and attachments, if the underlying feature service supports editing.

Features can be retrieved from the server as the app is used, or alternatively downloaded when the device is connected, and cached locally for use when the device is offline. Choosing the most appropriate API option enables your app to provide the workflows required, and allows it to adapt to the requirements of the situation. See the sections below for more information on the different options available.


API classes: AGSFeatureTableLayer (based on a AGSGDBFeatureServiceTable)—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 AGSGDBFeatureServiceTable, then create a AGSFeatureTableLayer by passing in the AGSGDBFeatureServiceTable to the constructor, and finally add the AGSFeatureTableLayer to the map. The AGSGDBFeatureServiceTable class is a subtype of AGSGDBFeatureTable, which is used for offline feature layers.


API classes: AGSGDBFeatureTable, AGSFeatureTableLayer—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 AGSGDBSyncTask.

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

Functional characteristics

As the feature attribute, geometry, and 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 feature service the layer was originally created from supports syncing, 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.

Performance characteristics

As full feature information is cached locally, 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 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), which may be a suitable workflow if the data is not changing too frequently.

ArcGIS feature service layers

API classes: AGSFeatureLayer—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.


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. Use the outFields property on the AGSFeatureLayer class.

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. Use the maxAllowableOffset field on the AGSFeatureLayer class.

Mode—Feature service layers support three different modes, which significantly affect the functionality and performance of the layer. Set the mode you require in the mode field of the AGSFeatureLayer passed to the feature layer constructor.

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

Dynamic map service layers

API classes: AGSDynamicMapServiceLayer, AGSImageServiceLayer—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: AGSGraphicsLayer—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 repsonse 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 AGSGraphicsLayerRenderingMode 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 AGSGroupLayer 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 AGSWMSLayer is used to add WMS services to a map.
  • Message groups—Message group layers display graphics with military symbols from one of the supported symbol dictionary types.
  • Bing maps—Bing maps services can be added as layers in a map by using the specialist AGSBingMapLayer 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 AGSOpenStreetMapLayer class. These services are tiled map services that usually provide basemap layers for a map