Basemap layers

What is a basemap layer?

A basemap layer is a layer that provides the overall visual context for a map or scene. It typically contains geographic features such as continents, lakes, administrative boundaries, streets, cities, and place names. These features are represented with different styles provided by the basemap layer service such as streets, topographic, and imagery. The style you choose depends on the type of application and the visualization you would like to create.

You can use a basemap layer to:

• Display different types of geographic data of the world for both maps and scenes.
• Display default vector tile basemap styles such as streets navigation, light gray canvas, and osm.
• Display custom basemap styles with your own colors, glyphs, and fonts.
• Display default image tile basemap layers for satellite imagery and hillshade.

How a basemap layer works

A basemap layer provides the visual foundation for a mapping application. It typically contains data with global coverage and is the first layer added to a map or scene. The main data source for a basemap layer is the basemap layer service. When a view displays a map, a basemap layer is the first layer to draw, followed by data layers, and then graphics.

Figure 1: A basemap layer provides visual context for a map or scene.

Types of basemap layers

The Basemap layer service provides a number of vector tile and image tile basemap layers that you can use to build different types of mapping applications. Each of the basemap layer styles is defined in an enumeration. For example, you can use the Navigation style to create an application that supports driving directions, or you can use Imagery to create an application that displays a real-world view of the earth.

Vector tile basemaps

Vector tile basemaps are pre-styled vector tile layers provided by the basemap layer service. Vector tile layers are high-performance and well suited for displaying high density geographic data as vector tile data. Vector tile layers are based on the Mapbox specification.

To access the default vector tile basemaps styles, most APIs provide enumerations. If they are not available, you can access them directly with the service URL.

Service URL

1
https://basemaps-api.arcgis.com/arcgis/rest/services/styles/{basemapStyle}?type={type}&token=<ACCESS_TOKEN>

Example vector tile basemap styles

• ArcGIS:LightGray
• ArcGIS:DarkGray
• ArcGIS:Navigation
• ArcGIS:NavigationNight
• ArcGIS:Streets
• ArcGIS:StreetsNight
• ArcGIS:Topographic
• OSM:Standard

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
// Fix blank line

esriConfig.apiKey = "YOUR_API_KEY";
const basemapEnum = "arcgis-streets" // arcgis-imagery, arcgis-navigation, arcgis-light-gray
const map = new Map({
  basemap: basemapEnum
});



esriConfig.apiKey = "YOUR_API_KEY";
const map = new Map({
  basemap: "arcgis-imagery"
});



esriConfig.apiKey = "YOUR_API_KEY";
const basemap = new Basemap({
  baseLayers: [

    new TileLayer({
      portalItem: {
        id: "1b243539f4514b6ba35e7d995890db1d" // World Hillshade
      }
    }),

    new VectorTileLayer({
      portalItem: {
        id: "d2ff12395aeb45998c1b154e25d680e5" // Forest and Parks Canvas
      },
      opacity: 0.5
    })
  ]
});

Custom vector tile basemap styles

A custom basemap layer style, also known as a basemap style, is a style that you define to create a custom visualization for a vector tile basemap layer. To do so, you use the ArcGIS Vector Tile Style Editor. You can edit any of the layer's properties such as the fill color, glyphs, and fonts for labels. After styling a basemap, you can save it in ArcGIS Online, and then use it in your applications.

Image tile basemaps

Image tile layers are pre-rendered images hosted in ArcGIS. The images are pre-rendered and stored on the server at different scales and resolutions. Client applications request images for the appropriate scale and zoom level for the map.

The URL and the most common image tile basemap styles are listed below.

Service URL

1
https://basemaps-api.arcgis.com/arcgis/rest/services/styles/{basemapStyle}?type={type}&token=<ACCESS_TOKEN>

Example image tile basemap styles

• ArcGIS:Imagery
• ArcGIS:Imagery:Standard
• ArcGIS:Imagery:Labels
• ArcGIS:Oceans
• ArcGIS:Hillshade:Light
• ArcGIS:Hillshade:Dark

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
// Fix blank line

esriConfig.apiKey = "YOUR_API_KEY";
const basemapEnum = "arcgis-streets" // arcgis-imagery, arcgis-navigation, arcgis-light-gray
const map = new Map({
  basemap: basemapEnum
});



esriConfig.apiKey = "YOUR_API_KEY";
const map = new Map({
  basemap: "arcgis-imagery"
});



esriConfig.apiKey = "YOUR_API_KEY";
const basemap = new Basemap({
  baseLayers: [

    new TileLayer({
      portalItem: {
        id: "1b243539f4514b6ba35e7d995890db1d" // World Hillshade
      }
    }),

    new VectorTileLayer({
      portalItem: {
        id: "d2ff12395aeb45998c1b154e25d680e5" // Forest and Parks Canvas
      },
      opacity: 0.5
    })
  ]
});

Multi-layer basemap layers

A basemap layer can be composed of one or more layers. Many default styles combine multiple layers. For example:

• ArcGIS:StreetsRelief combines a layer of streets with a backing hillshade layer to provide topographic context.

  ArcGIS:StreetsRelief uses ArcGIS:StreetsRelief:Base overlaid on top of ArcGIS:Hillshade:Light.

• ArcGIS:Imagery combines a layer of satellite imagery with a reference layer of labels and boundaries.

  ArcGIS:Imagery uses ArcGIS:Imagery:Standard as the base layer and ArcGIS:Imagery:Labels as the reference layer.

See Basemap layer service to learn more.

You can create your own multi-layer basemap by combining layers and specifying which should be treated as reference layers. See the Display a multi-layer basemap layer example.

Examples

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
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
<html>

<head>
  <meta charset="utf-8">
  <meta name="viewport" content="initial-scale=1, maximum-scale=1, user-scalable=no">
  <title>ArcGIS Developer Guide: Display a map (2D)</title>
  <style>
    html,
    body,
    #viewDiv {
      padding: 0;
      margin: 0;
      height: 100%;
      width: 100%;
    }
  </style>

  <link rel="stylesheet" href="https://js.arcgis.com/4.22//esri/themes/light/main.css">
  <script src="https://js.arcgis.com/4.22//"></script>

  <script>
    require([
      "esri/config",
      "esri/Map",
      "esri/views/MapView"
    ],(esriConfig, Map, MapView)=> {

      esriConfig.apiKey = "YOUR_API_KEY";

      const map = new Map({
        basemap: "arcgis-topographic",
        //basemap: "arcgis-imagery"
        //basemap: "arcgis-navigation"
        //basemap: "arcgis-light-gray"
      });

      const view = new MapView({
        map: map,
        center: [-118.805, 34.027],
        zoom: 13,
        container: "viewDiv",
        constraints: {
          snapToZoom: false
        }
      });


      view.ui.add(locate, "top-left");

    });
  </script>
</head>

<body>
  <div id="viewDiv"></div>
</body>

</html>

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
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
<html>
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="initial-scale=1, maximum-scale=1, user-scalable=no">
  <title>ArcGIS Developer Guide: Display a multi-layer basemap layer</title>
  <style>
    html, body, #viewDiv {
      padding: 0;
      margin: 0;
      height: 100%;
      width: 100%;
    }
  </style>  <link rel="stylesheet" href="https://js.arcgis.com/4.18/esri/themes/light/main.css">
  <script src="https://js.arcgis.com/4.18/"></script>
  <script>

  require([
    "esri/config",
    "esri/Map",
    "esri/views/MapView",
    "esri/Basemap",
    "esri/layers/VectorTileLayer",
    "esri/layers/TileLayer",

  ],(esriConfig, Map, MapView, Basemap, VectorTileLayer, TileLayer)=> {

    esriConfig.apiKey = "YOUR_API_KEY";

  const vectorTileLayer = new VectorTileLayer({
    portalItem: {
      id: "6976148c11bd497d8624206f9ee03e30" // Forest and Parks Canvas
    },
    opacity: .75
  });

  const imageTileLayer = new TileLayer({
    portalItem: {
      id: "1b243539f4514b6ba35e7d995890db1d" // World Hillshade
    }
  });

  const basemap = new Basemap({
    baseLayers: [

      imageTileLayer,
      vectorTileLayer

    ]
  });

  const map = new Map({
    basemap: basemap,
  });

  const view = new MapView({
    container: "viewDiv",
    map: map,
    center: [-100,40],
    zoom: 3,
    constraints: {
          snapToZoom: false
        }
  });

  });
  </script>
</head>
<body>
  <div id="viewDiv"></div>
</body>
</html>

Tutorials

Display a map

Create and display a map with the basemap layer service.

Display a scene

Display a scene with the basemap layer service.

Add a point, line, and polygon

Display point, line, and polygon graphics in a map.

Add a feature layer

Access and display point, line, and polygon features from a feature service

Display a web map

Create and display a map from a web map.

Display a web scene

Create and display a scene from a web scene.

Change the basemap layer

Switch a basemap layer from streets to satellite imagery.

Services

API support

Tools