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

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

1
 https://basemapstyles-api.arcgis.com/arcgis/rest/services/styles/v2/{type}/{provider}/{basemapStyle}?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:

1
https://ibasemaps-api.arcgis.com/arcgis/rest/services/Ocean/World_Ocean_Base/MapServer/tile/{z}/{y}/{x}?token=<ACCESS_TOKEN>

1
https://ibasemaps-api.arcgis.com/arcgis/rest/services/Elevation/World_Hillshade/MapServer/tile/{z}/{y}/{x}?token=<ACCESS_TOKEN>

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)

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,
          },
        })

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
    }
  });

Basemap styles service v2 (beta)

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]
});

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]
});

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]
});

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]
});

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

Display a map

Create and display a map with the basemap styles service.

JavaScript .NET Kotlin Swift Java Qt Esri Leaflet MapLibre OpenLayers 

Display a scene

Display a scene with the basemap styles service.

JavaScript .NET Kotlin Swift Java Qt CesiumJS 

Add a point, line, and polygon

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

JavaScript .NET Kotlin Swift Java Qt 

Add a feature layer

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

JavaScript .NET Kotlin Swift Java Qt Esri Leaflet MapLibre OpenLayers CesiumJS 

Display a web map

Create and display a map from a web map.

JavaScript .NET Kotlin Swift Java Qt 

Display a web scene

Create and display a scene from a web scene.

JavaScript .NET Kotlin Swift Java Qt 

Change the basemap layer

Switch a basemap layer from streets to satellite imagery.

JavaScript Esri Leaflet MapLibre OpenLayers CesiumJS 

Change the place label language

Switch the language of place labels on a basemap.

MapLibre OpenLayers 

Services

API support

Tools