Basemap layers

Community basemap layer and a widget with more basemap styles

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}?token={apiKey}

Example vector tile basemap styles

  • ArcGIS:LightGray
  • ArcGIS:DarkGray
  • ArcGIS:Navigation
  • ArcGIS:NavigationNight
  • ArcGIS:Streets
  • ArcGIS:StreetsNight
  • ArcGIS:Topographic
  • OSM:Standard
ArcGIS JS APIEsri LeafletMapbox GL JSOpenLayersArcGIS .NET APIArcGIS Android APIArcGIS iOS APIArcGIS Java APIArcGIS Qt API (C++)ArcGIS Qt API (QML)
                                   
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 the ArcGIS Platform. 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}?token={apiKey}

Example image tile basemap styles

  • ArcGIS:Imagery
  • ArcGIS:Imagery:Standard
  • ArcGIS:Imagery:Labels
  • ArcGIS:Oceans
  • ArcGIS:Hillshade:Light
  • ArcGIS:Hillshade:Dark
ArcGIS JS APIEsri LeafletMapbox GL JSOpenLayersArcGIS .NET APIArcGIS Android APIArcGIS iOS APIArcGIS Java APIArcGIS Qt API (C++)ArcGIS Qt API (QML)
                                   
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

Display a basemap layer

This example shows how to use different enumerations to display basemap layers from the basemap layer services. Where enumerations are not available, you can access the service style or layer with its URL.

Steps

  1. Create a map or scene.
  2. Reference a basemap layer from the basemap layer service.
  3. Add the basemap to the map or scene.
  4. Use an interface to allow users to change the basemap layer.

Topographic

Imagery

Light gray canvas

ArcGIS JS APIEsri LeafletMapbox GL JSOpenLayersArcGIS .NET APIArcGIS Android APIArcGIS iOS APIArcGIS Java APIArcGIS Qt API (C++)ArcGIS Qt API (QML)
                                                          
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.19//esri/themes/light/main.css">
  <script src="https://js.arcgis.com/4.19//"></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>

Display a multi-layer basemap layer

This example shows how to use multiple layers together as a single basemap layer. You can use item IDs for each layer in a multi-layer basemap layer.

Steps

  1. Reference two or more layers using their item IDs.
  2. Create a basemap that uses these layers as base layers or reference layers.
  3. Create a map or scene using the basemap.
ArcGIS JS APIEsri LeafletMapbox GL JSOpenLayersArcGIS .NET APIArcGIS Android APIArcGIS iOS APIArcGIS Java APIArcGIS Qt API (C++)ArcGIS Qt API (QML)
                                                                       
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: [
  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

Services

Basemap layer service

Access streets, satellite, and other basemap styles for maps and scenes.

API support

2D Display3D DisplayBasemap layersData layersGraphicsWeb mapsWeb scenes
ArcGIS API for JavaScriptFully supportedFully supportedFully supportedFully supportedFully supportedFully supportedFully supported
ArcGIS Runtime API for AndroidFully supportedFully supportedFully supportedFully supportedFully supportedFully supportedFully supported
ArcGIS Runtime API for iOSFully supportedFully supportedFully supportedFully supportedFully supportedFully supportedFully supported
ArcGIS Runtime API for JavaFully supportedFully supportedFully supportedFully supportedFully supportedFully supportedFully supported
ArcGIS Runtime API for .NETFully supportedFully supportedFully supportedFully supportedFully supportedFully supportedFully supported
ArcGIS Runtime API for QtFully supportedFully supportedFully supportedFully supportedFully supportedFully supportedFully supported
ArcGIS API for PythonFully supportedNot supportedFully supportedFully supportedFully supportedFully supportedFully supported
Esri LeafletFully supportedNot supportedFully supportedFeature layer, Image tile layerLeaflet LayersNot supportedNot supported
MapBox GL JSFully supportedNot supportedFully supportedFeature layer, Image tile layerMapbox LayersNot supportedNot supported
OpenLayersFully supportedNot supportedFully supportedFeature layer, Image tile layerOpenSource LayersNot supportedNot supported
ArcGIS REST JSNot supportedNot supportedDirect access and authenticationDirect access and authenticationNot supportedDirect access and authenticationDirect access and authentication
Full supportPartial support (see notes)Not supported

Tools

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