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 styles 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 styles 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 styles

The basemap styles service provides a number of vector tile and image tile basemap styles that you can use to build different types of mapping applications. 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.

Currently, there are two versions of the basemap styles service available: the basemap styles service (v1) and the basemap styles service v2 (beta).

Vector basemap stylesImage basemap stylesLocalized place labelsHTTP header authenticationOpen source librariesArcGIS Maps SDKs
Basemap styles service (v1)
Basemap styles service v2 (beta)12
Full supportPartial supportNo support
  • 1. MapLibre GL JS and OpenLayers
  • 2. ArcGIS Maps Native SDKs

Vector tile basemaps

Vector tile basemaps are pre-styled vector tile layers provided by a basemap styles 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.

Service URL

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.

Enumerations include:

  • ArcGIS:Streets
  • ArcGIS:Navigation
  • OSM:Streets
Use dark colors for code blocksCopy
 
1
https://basemaps-api.arcgis.com/arcgis/rest/services/styles/{basemapStyle}?type={type}&token=<ACCESS_TOKEN>

Image tile basemaps

Image tile layers are pre-rendered images hosted in ArcGIS and are served as images from https://ibasemaps-api.arcgis.com. The images are stored on the server at different scales and resolutions. Client applications request images for the appropriate scale and zoom level for the map. Styles include:

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

Image tile service URLs are the same for both version one and version two of the service.

To learn more, go to Basemap styles service (v1) or Basemap styles service v2 (beta).

Image tile service URL

You can access image tiles directly by referencing the service URL and specifying the serviceName.

Template URL examples:

Use dark colors for code blocksCopy
 
1
https://ibasemaps-api.arcgis.com/arcgis/rest/services/Ocean/World_Ocean_Base/MapServer/tile/{z}/{y}/{x}?token=<ACCESS_TOKEN>
Use dark colors for code blocksCopy
 
1
https://ibasemaps-api.arcgis.com/arcgis/rest/services/Elevation/World_Hillshade/MapServer/tile/{z}/{y}/{x}?token=<ACCESS_TOKEN>
Use dark colors for code blocksCopy
 
1
https://ibasemaps-api.arcgis.com/arcgis/rest/services/World_Imagery/MapServer/tile/{z}/{y}/{x}?token=<ACCESS_TOKEN>

Multi-layer basemap layers

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

  • ArcGIS Streets Relief combines a layer of streets (ArcGIS Streets Relief Base) with a backing hillshade layer (ArcGIS Hillshade Light) to provide topographic context.
  • ArcGIS Imagery combines a layer of satellite imagery (ArcGIS Imagery Standard) with a reference layer (ArcGIS Imagery Labels) of labels and boundaries.

See Basemap styles service (v1) or Basemap styles service v2 (beta).

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.

Code examples

Basemap styles service (v1)

Display a basemap style

This example shows how to use different enumerations to display styles from the basemap styles service (v1).

Steps

  1. Create a map or scene.
  2. Reference a basemap layer from the basemap styles 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 Maps SDK for JavaScriptArcGIS Maps SDK for JavaScriptArcGIS Maps SDK for .NETArcGIS Maps SDK for KotlinArcGIS Maps SDK for SwiftArcGIS Maps SDK for JavaArcGIS Maps SDK for Qt (C++)ArcGIS Maps SDK for Qt (QML)ArcGIS API for PythonEsri LeafletMapLibre GL JSOpenLayers
Expand
Use dark colors for code blocksCopy
                                                        
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
        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,
          },
        })

Display a multi-layer basemap layer (v1)

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 using the basemap.
ArcGIS Maps SDK for JavaScriptArcGIS Maps SDK for JavaScriptArcGIS Maps SDK for .NETArcGIS Maps SDK for KotlinArcGIS Maps SDK for SwiftArcGIS Maps SDK for JavaArcGIS Maps SDK for Qt (C++)ArcGIS Maps SDK for Qt (QML)Esri LeafletMapLibre GL JSOpenLayers
Expand
Use dark colors for code blocksCopy
                                                                       
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
  const vectorTileLayer = new VectorTileLayer({
    portalItem: {
      id: "6976148c11bd497d8624206f9ee03e30" // Forest and Parks Canvas
    },
    opacity: .75
  });

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

Basemap styles service v2 (beta)

Display a basemap style

The basemap styles service (v2) provides additional ArcGIS and OSM basemap styles, including outdoor, OSM navigation, and OSM blueprint. To learn more, go to Basemap styles service (v2).

Steps

  1. Create a map.
  2. Reference a basemap layer from the basemap styles service v2 (beta).
  3. Add the basemap to the map.

Outdoor

MapLibre GL JSMapLibre GL JSOpenLayers
Use dark colors for code blocksCopy
                                    
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
const map = new maplibregl.Map({
  container: "map", // ID of the div element
  style: `https://basemapstyles-api.arcgis.com/arcgis/rest/services/styles/v2/styles/arcgis/outdoor?token=${apiKey}`,
  zoom: 13,
  center: [-119.52, 37.74] // Starting location [longitude, latitude]
});

OSM Navigation

MapLibre GL JSMapLibre GL JSOpenLayers
Use dark colors for code blocksCopy
                                    
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
const map = new maplibregl.Map({
  container: "map", // ID of the div element
  style: `https://basemapstyles-api.arcgis.com/arcgis/rest/services/styles/v2/styles/osm/navigation?token=${apiKey}`,
  zoom: 13,
  center: [2.35, 48.856] // Starting location [longitude, latitude]
});

OSM Blueprint

MapLibre GL JSMapLibre GL JSOpenLayers
Use dark colors for code blocksCopy
                                    
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
const map = new maplibregl.Map({
  container: "map", // ID of the div element
  style: `https://basemapstyles-api.arcgis.com/arcgis/rest/services/styles/v2/styles/osm/blueprint?token=${apiKey}`,
  zoom: 13,
  center: [-122.67, 45.51] // Starting location [longitude, latitude]
});

Localize place labels

An ArcGIS basemap style renders place labels using the default global language setting, typically in English. The OSM map styles, however, render localized place labels. The basemap styles service (v2) provides additional language support so that you can customize the place lable language.

Steps

  1. Create a map or scene.
  2. Reference a basemap layer from the basemap styles service v2 (beta).
  3. In the style URL, set the language parameter with a language code.
  4. Add the basemap to the map.

Localized place labels (local)

This example uses the ArcGIS Light Gray map style. By default, place labels display global place names. To render localized place labels, set the language parameter to local. The localized labels will render after zoom level 10.

MapLibre GL JSMapLibre GL JSOpenLayers
Use dark colors for code blocksCopy
                                    
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
const map = new maplibregl.Map({
  container: "map", // ID of the div element
  style: `https://basemapstyles-api.arcgis.com/arcgis/rest/services/styles/v2/styles/arcgis/light-gray?token=${apiKey}&language=local`,
  zoom: 3,
  center: [100.501, 13.756] // Starting location [longitude, latitude]
});

Language-based place labels (global)

This example uses the ArcGIS Dark Gray map style. It sets the language parameter with a language code, in this case ja, so that all place labels at varying zoom levels are rendered in Japanese.

MapLibre GL JSMapLibre GL JSOpenLayers
Use dark colors for code blocksCopy
                                    
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
const map = new maplibregl.Map({
  container: "map", // ID of the div element
  style: `https://basemapstyles-api.arcgis.com/arcgis/rest/services/styles/v2/styles/arcgis/dark-gray?token=${apiKey}&language=ja`,
  zoom:3,
  center: [138.25, 36.20] // Starting location [longitude, latitude]
});

Tutorials

Services

API support

Full supportPartial supportNo support
  • 1. Access via HTTP request and authentication.
  • 2. Access via Feature layer or Image tile layer.
  • 3. Access via layers.

Tools

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