Introduction to layers

Layers are collections of data that can be used in a Map. Layer data can be created on the client, hosted by ArcGIS Online and ArcGIS Enterprise, or hosted by external servers.

The ArcGIS Maps SDK for JavaScript has a number of layer classes that can be used to access and display data. All classes inherit from Layer. The class used depends on the format of the data and where the data is stored. Each layer type also exposes a different set of capabilities.

Below is a list of some layer classes. See Layer for the complete list.

Displaying data sources with a FeatureLayer

A FeatureLayer is a layer that references a collection of geographic features. All features in the collection must have the same geometry type and attribute keys.

Feature layer data sources can be either in memory from data loaded by the application or the layer will request data from a REST API service hosted on ArcGIS Online or ArcGIS Enterprise. Hosting your data in ArcGIS Online or ArcGIS Enterprise is the preferred method, especially for accessing and displaying large amounts of geographic data. Feature layers are highly optimized on both the client and the server for fast display and support a variety of other features including

• User interaction and popups
• Client side filtering, querying and analysis
• Editing
• Data driven visualization

ArcGIS Developers and ArcGIS Online provide tools for importing data such as GeoJSON, Excel, CSV, file geodatabases, and shapefiles. Importing data creates a feature layer item in ArcGIS Online that can be used as a server-side data source.

Client-side data sources

Typically layer data is loaded from a REST API service hosted on ArcGIS Online or ArcGIS Enterprise, however, it is also possible to create a feature layer directly from a collection of features in memory.

For example, a collection of features in Los Angeles, California, is given below in JSON format. This data can be transformed into a format acceptable for displaying in a FeatureLayer.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
{
  "places": [
    {
      "id": 1,
      "address": "200 N Spring St, Los Angeles, CA 90012",
      "longitude": -118.24354,
      "latitude": 34.05389
    },
    {
      "id": 2,
      "address": "419 N Fairfax Ave, Los Angeles, CA 90036",
      "longitude": -118.31966,
      "latitude": 34.13375
    }
  ]
}

The first step to create a feature layer from the above JSON data is to transform each place into a Graphic object with the attributes and geometry properties.

The following code sample transforms the array of places into an array of Graphic objects.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
const graphics = places.map((place) => {
  return new Graphic({
    attributes: {
      ObjectId: place.id,
      address: place.address
    },
    geometry: {
      type: "point",
      longitude: place.longitude,
      latitude: place.latitude
    },
    symbol: {
      // autocasts as new SimpleMarkerSymbol()
      type: "simple-marker",
      color: [226, 119, 40],
      outline: {
        // autocasts as new SimpleLineSymbol()
        color: [255, 255, 255],
        width: 2
      }
    }
  });
});

The second step in creating a FeatureLayer is to actually create a FeatureLayer object, and specify at least the objectIdField, fields, renderer, and source properties described in the following table.

The following code sample creates a new FeatureLayer and explicitly sets the source property to graphics. Autocasting is used to set the renderer, popup, and fields properties.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
const featureLayer = new FeatureLayer({
  source: graphics,
  renderer: {
    type: "simple",                    // autocasts as new SimpleRenderer()
    symbol: {                          // autocasts as new SimpleMarkerSymbol()
      type: "simple-marker",
      color: "#102A44",
      outline: {                       // autocasts as new SimpleLineSymbol()
        color: "#598DD8",
        width: 2
      }
    }
  },
  popupTemplate: {                     // autocasts as new PopupTemplate()
    title: "Places in Los Angeles",
    content: [{
      type: "fields",
      fieldInfos: [
        {
          fieldName: "address",
          label: "Address",
          visible: true
        }
      ]
    }]
  },
  objectIdField: "ObjectID",           // This must be defined when creating a layer from `Graphic` objects
  fields: [
    {
      name: "ObjectID",
      alias: "ObjectID",
      type: "oid"
    },
    {
      name: "address",
      alias: "address",
      type: "string"
    }
  ]
});

map.layers.add(featureLayer);

Server-side data sources

FeatureLayer also supports collections of features returned from a a REST API service specified with by the url property. This is the most effective way to access and display large datasets. The feature layer will work with the feature service to retrieve features as efficiently as possible and, if enabled, will provide access to additional capabilities such as editing.

1
2
3
4
5
var layer = new FeatureLayer({
  url: "https://services3.arcgis.com/GVgbJbqm8hXASVYi/arcgis/rest/services/Trailheads/FeatureServer/0"
});

map.layers.add(layer);

In addition to URLs you can also reference layer items stored in ArcGIS Online or ArcGIS Enterprise. These items reference a REST API service which stores the layer's data as well as additional configuration options.

1
2
3
4
5
6
7
8
var layer = new FeatureLayer({
  portalItem: {
    id: "883cedb8c9fe4524b64d47666ed234a7",
    portal: "https://www.arcgis.com"               // Default: The ArcGIS Online Portal
  }
});

map.layers.add(layer);

Displaying graphics with a GraphicsLayer

Graphics are typically used for adding text, shapes, and images with different geometries to a map. The simplest way to create a graphics layer is to create Graphic objects as an array, and pass this array to the graphics property of a new GraphicsLayer object.

Every Graphic class includes the following properties:

The below code sample creates a new Graphic object with a Point geometry type, a popup, and a symbol. It then creates a new GraphicsLayer by passing an array of graphics to the graphics property.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
var pointGraphic = new Graphic({
  attributes: {
    name: "LA City Hall",
    address: "200 N Spring St, Los Angeles, CA 90012"
  },
  geometry: {
    type: "point",                     // autocasts as new Point()
    longitude: -118.24354,
    latitude: 34.05389
  },
  symbol: {
    type: "simple-marker",             // autocasts as new SimpleMarkerSymbol()
    color: [ 226, 119, 40 ],
    outline: {                         // autocasts as SimpleLineSymbol()
      color: [ 255, 255, 255 ],
      width: 2
    }
  },
  popupTemplate: {                     // autocasts as new PopupTemplate()
    title: "Places in Los Angeles",
    content: [{
      type: "fields",
      fieldInfos: [
        {
          fieldName: "name",
          label: "Name",
          visible: true
        },
        {
          fieldName: "address",
          label: "Address",
          visible: true
        }
      ]
    }]
  },
});

var graphicsLayer = new GraphicsLayer({
  graphics: [ pointGraphic ]
});

map.layers.add(graphicsLayer);

Working with external data sources

Additional types of data and files are directly supported by specific subclasses of Layer. These include specific types of layers for working with external files like CSV or GeoJSON files or integrating external services such as Bing Maps.

Each of these layers requires different properties depending on how they are initialized. Refer to each layer type for more details. An example of creating a CSVLayer layer is shown below.

1
2
3
4
5
6
7
8
var earthquakesLayer = new CSVLayer({
  url: "https://earthquake.usgs.gov/earthquakes/feed/v1.0/summary/2.5_week.csv",
  copyright: "USGS Earthquakes",
  latitudeField: "latitude", // Defaults to "latitude"
  longitudeField: "longitude" // Defaults to "longitude"
});

map.layers.add(earthquakesLayer)

Using basemaps and tile layers

Basemaps are used to provide geographic context to a map by displaying roads, boundaries, buildings and other data. Basemaps are often served as tiles for faster rendering. Raster basemaps request pre-created images. Vector basemaps request data in a compressed binary format and style it on the client. The ArcGIS contains a curated set of basemaps.

Vector basemaps can be customized with the the Vector Tile Style Editor. Custom data can also be published as vector or raster tiles with ArcGIS Online or ArcGIS Enterprise.

The basemap for a specific Map object can be controlled with the basemap property which can be a string identifying a specific basemap or a Basemap object.

1
2
3
var Map = new Map({
  basemap: "streets-navigation-vector"
})

Working with Map Services from ArcGIS Enterprise

MapImageLayer is used to display data from a Map Service in ArcGIS Enterprise. Map Services often contain multiple sub layers and complex cartography. Map Services render data as a server side image that is dynamically generated and displayed on the client.

Using raster and imagery data

ImageryLayer is used to display imagery or other raster based data stored in an Image Service in ArcGIS Enterprise. ImageryLayer is often used to display and analyze raw imagery data captured from drones or satellites or for displaying scientific data.

Data as collections of features

Layers are often used to manage and display large collections of features. Features are records of geographical locations or entities. Every feature contains spatial coordinates defined for a type of geometry (point, polyline, or polygon) and attribute fields that store other information. These collections of features can be thought of as:

• Structured if every feature has the same geometry type and the same attributes keys
• Unstructured if any features have different geometry types or different attributes keys

When working with a collection of features the general rule of thumb is:

• If the data is structured use FeatureLayer to display the data
• If unstructured use GraphicsLayer to display the data