Basemaps

What is a basemap?

A basemap, also known as a basemap layer, is a layer that provides the overall visual context for a map or scene. It typically contains geographic features and labels for continents, lakes, administrative boundaries, streets, cities, and places. The most common data sources for a basemap are the basemap styles service and data services.

You can use a basemap layer to:

• Display different types of geographic data of the world for both maps and scenes.
• Display basemap styles such as ArcGIS streets, navigation, or light gray canvas, or OSM streets.
• Display custom basemap styles with your own colors, glyphs, and fonts.
• Display vector tile layers for streets or navigation.
• Display map tile layers for satellite imagery or hillshade.
• Display your own data services with their own spatial references.

How a basemap 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. When a view displays a map, the 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 data sources

Two common data sources for a basemap are the basemap styles service and data services.

Basemap styles service

The basemap styles service is a location service API that provides basemap styles and data for the extent of the world. Each basemap style has a unique set of visual properties for geographic features and labels. The service includes two data providers: ArcGIS and OSM. The data providers supports default basemap styles such as streets, navigation, light gray canvas, and imagery. The data for each style is provided through vector tile layers and map tile layers hosted in ArcGIS and is stored in the web mercator spatial reference.

The general steps to use the basemap style service are:

1. Explore the default basemap styles available with the basemap styles service.

2. Reference the service, data provider, and style.

   • Data providers: ArcGIS or OSM.
   • Basemap styles: E.g. streets, imagery, navigation, topography, light gray canvas, or outdoors.

3. Display the basemap.

The ArcGIS Maps SDKs provide enumerations or helper classes to access each style. When using open source libraries, however, you need to reference the basemap styles service or the underlying vector tile or map tile layers directly.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
esriConfig.apiKey = "YOUR_ACCESS_TOKEN";
const map = new Map({
  basemap: "arcgis/navigation"
});

Data services

Data services such as feature services, vector tile services, and map tile services are services hosted in ArcGIS or ArcGIS Enterprise that contain your data. In most cases, any data service supported by a client API can be used as a data source for a basemap. Data services can be accessed and managed with a hosted layer (item) in ArcGIS.

The general steps to use a data service are:

1. Find or create a hosted layer and data service:
   • Find existing services in ArcGIS Online and ArcGIS Living Atlas of the World.
   • Learn how to create your own data services in Data hosting.
2. Get the layer item ID or service URL. For example:
   • Layer item: https://www.arcgis.com/home/item.html?id=4d9fb5c0a6344407aec56f47a11482b5
   • Item ID: 4d9fb5c0a6344407aec56f47a11482b5
   • Service URL: https://services2.arcgis.com/FiaPA4ga0iQKduv3/arcgis/rest/services/State_Geologic_Map_Compilation_%E2%80%93_Geology/FeatureServer/0
3. Display the basemap.

ArcGIS Maps SDKs access data services with a hosted layer item ID or service URL. Open source libraries however access data services with the service URL.

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
  const featureLayer = new FeatureLayer({
    portalItem: {
      id: "4d9fb5c0a6344407aec56f47a11482b5" // State Geologic Map Compilation – Geology
    }
  });
  const basemap = new Basemap({
    baseLayers: [featureLayer]
  });

Code 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
59
60
61
        esriConfig.apiKey = "YOUR_ACCESS_TOKEN"

        const map = new Map({
          basemap: "arcgis/streets",
          //basemap: "arcgis/navigation"
          //basemap: "arcgis/topographic"
          //basemap: "arcgis/outdoor"
          //basemap: "arcgis/light-gray"
          //basemap: "arcgis/imagery"
          //basemap: "osm/standard"
          //basemap: "osm/navigation"
          //basemap: "osm/blueprint"
        })

        const view = new MapView({
          map: map,
          center: [-118.805, 34.027],
          zoom: 12,
          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
const apiKey = "YOUR_ACCESS_TOKEN";
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);

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_ACCESS_TOKEN";
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);

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

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
  const featureLayer = new FeatureLayer({
    portalItem: {
      id: "4d9fb5c0a6344407aec56f47a11482b5" // State Geologic Map Compilation – Geology
    }
  });
  const basemap = new Basemap({
    baseLayers: [featureLayer]
  });

Tutorials

Change the basemap layer

Switch a basemap layer from streets to satellite imagery.

JavaScript Maps SDKEsri LeafletMapLibre GL JSOpenLayersCesiumJS

Change the place label language

Switch the language of place labels on a basemap.

JavaScript Maps SDKEsri LeafletMapLibre GL JSOpenLayers

Create a custom basemap style

Use the Vector Tile Style Editor to style a vector tile basemap layer.

Vector Tile Style Editor

Display a custom basemap style

Add and display a styled vector tile basemap layer.

JavaScript Maps SDKEsri LeafletMapLibre GL JSOpenLayers

Display basemap places

Learn how to use the basemap styles service to show place locations on a basemap.

MapLibre GL JS