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

	Vector basemap styles	Image basemap styles	Localized place labels	HTTP header authentication	Open source libraries	ArcGIS Maps SDKs
Basemap styles service (v1)
Basemap styles service (v2)					¹	²

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
https://basemaps-api.arcgis.com/arcgis/rest/services/styles/{basemapStyle}?type={type}&token=<ACCESS_TOKEN>

To access vector basemap styles, you specify the type of JSON to be returned, webmaps or styles, the provider arcgis or osm, and the basemap style.

Styles inlcude:

arcgis/streets
arcgis/navigation
arcgis/outdoor

Use dark colors for code blocksCopy
 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.

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

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

Create a map or scene.
Reference a basemap layer from the basemap styles service.
Add the basemap to the map or scene.
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,
          },
        })

Expand

Go to tutorial

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

Reference two or more layers using their item IDs.
Create a basemap that uses these layers as base layers or reference layers.
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

Go to tutorial

Basemap styles service (v2)

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

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

Outdoor

Esri Leaflet

MapLibre GL JS

OpenLayers

Use dark colors for code blocks

Copy

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

const apiKey = "YOUR_API_KEY";
const map = L.map("map").setView([37.75, -122.23], 10);
L.esri.Vector.vectorBasemapLayer("arcgis/outdoor", {
  apikey: apiKey,
  version: 2
}).addTo(map);

Go to tutorial

Esri Leaflet

MapLibre GL JS

OpenLayers

Use dark colors for code blocks

Copy

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
const apiKey = "YOUR_API_KEY";
const map = L.map("map").setView([2.35, 48.856], 6);
L.esri.Vector.vectorBasemapLayer("osm/navigation", {
  apikey: apiKey,
  version: 2
}).addTo(map);

Go to tutorial

OSM Blueprint

Esri Leaflet

MapLibre GL JS

OpenLayers

Use dark colors for code blocks

Copy

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
const apiKey = "YOUR_API_KEY";
const map = L.map("map").setView([2.35, 48.856], 6);
L.esri.Vector.vectorBasemapLayer("osm/blueprint", {
  apikey: apiKey,
  version: 2
}).addTo(map);

Go to tutorial

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 label language.

Steps

Create a map or scene.
Reference a basemap layer from the basemap styles service (v2).
In the style URL, set the language parameter with a language code.
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.

Esri Leaflet

MapLibre GL JS

OpenLayers

Use dark colors for code blocks

Copy

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
const apiKey = "YOUR_API_KEY";
const map = L.map("map").setView([2.35, 48.856], 6);
L.esri.Vector.vectorBasemapLayer("arcgis/light-gray", {
  apikey: apiKey,
  language: 'local',
  version: 2
}).addTo(map);

Go to tutorial

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.

Esri Leaflet

MapLibre GL JS

OpenLayers

Use dark colors for code blocks

Copy

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
const apiKey = "YOUR_API_KEY";
const map = L.map("map").setView([2.35, 48.856], 6);
L.esri.Vector.vectorBasemapLayer("arcgis/dark-gray", {
  apikey: apiKey,
  language: 'ja',
  version: 2
}).addTo(map);

Go to tutorial

Select a worldview

An ArcGIS basemap style renders country boundaries and labels using the default global worldview. The basemap styles service (v2) allows you to display basemap borders and labels based on a specific view of a country. Worldviews are only available for some ArcGIS basemap styles such as navigation, streets, and community. OSM styles are not supported.

Steps

Create a map or scene.
Reference a basemap layer from the basemap styles service (v2).
In the style URL, set the worldview parameter with a supported worldview name.
Add the basemap to the map.

This example uses the ArcGIS light/gray map style and sets the worldview for boundaries and labels to morocco. To find all worldview options, go to Basemap styles service (v2).

MapLibre GL JSMapLibre GL JSOpenLayers
Expand
Use dark colors for code blocksCopy
      const worldView = "morocco"
      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}&worldview=${worldView}`,
        zoom: 3,
        center: [-7.09, 31], // Starting location [longitude, latitude]
      })
Expand

Tutorials

Display a map

Create and display a map with the basemap styles service.

Display a scene

Display a scene with the basemap styles 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.

Change the place label language

Switch the language of place labels on a basemap.

MapLibre

Services

Basemap styles service (v2)

Access additional basemap styles and customize language settings for place labels.

Basemap styles service (v1)

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

API support

	Basemap places	Data layers	Graphics
ArcGIS Maps SDK for JavaScript	¹
ArcGIS Maps SDK for .NET
ArcGIS Maps SDK for Kotlin
ArcGIS Maps SDK for Swift
ArcGIS Maps SDK for Java
ArcGIS Maps SDK for Qt
ArcGIS API for Python
ArcGIS REST JS		²	²
Esri Leaflet		³	⁴
MapLibre GL JS		³	⁴
OpenLayers	¹	³	⁴
CesiumJS		³	⁴

Full supportPartial supportNo support

1. Display places only.
2. Access via HTTP request and authentication.
3. Access via Feature layer or Map tile layer.
4. Access via layers.

Tools

Map Viewer

Create, explore, and share web maps for 2D applications.

Scene Viewer

Create, explore, and share web scenes for 3D applications.

Vector tile style editor

Style vector tile basemap layers for applications.

ArcGIS Pro

Explore, visualize, and analyze both 2D and 3D data with desktop GIS tools.

Mapping APIs and location services

Basemap layers

Was this page helpful?

Mapping APIs and location services

Basemap layers

What is a basemap layer?

How a basemap layer works

Types of basemap styles

Vector tile basemaps

Service URL

Image tile basemaps

Image tile service URL

Multi-layer basemap layers

Code examples

Basemap styles service (v1)

Display a basemap style

Steps

Topographic

Imagery

Navigation

Light gray canvas

Display a multi-layer basemap layer (v1)

Steps

Basemap styles service (v2)

Display a basemap style

Steps

Outdoor

OSM Navigation

OSM Blueprint

Localize place labels

Steps

Localized place labels (local)

Language-based place labels (global)

Select a worldview

Steps

Tutorials

Display a map

Display a scene

Add a point, line, and polygon

Add a feature layer

Display a web map

Display a web scene

Change the basemap layer

Change the place label language

Services

Basemap styles service (v2)

Basemap styles service (v1)

API support

Tools

Map Viewer

Scene Viewer

Vector tile style editor

ArcGIS Pro

Was this page helpful?