Display multiple basemap layers

Learn how to add multiple basemap layers from different services to your map.

This tutorial shows how to display two basemap layers from different services in your application. You will use the World Imagery map tile serviceA map tile service, formerly known as image tile service, is a data service that provides access to static, pre-rendered mao tiles. The tiles are typical in PNG format. Map tiles are typically retrieved by specifying a specific level, row, and column value.Learn more satellite imagery basemap to provide the underlying visual and geographic context for the map. To provide additional context, you will use the arcgis/imagery/labels style from the ArcGIS Static Basemap Tiles serviceThe ArcGIS Static Basemap Tiles service, also known as the Static Basemap Tiles service, is a location service that provides basemap data as pre-rendered and pre-styled map tiles for the world. It supports key styles in the ArcGIS Basemap style family. An ArcGIS Location Platform account is required to use the services.Learn more to display place labels for the world. The combination of the two layers will result in a basemap that provides additional context for the mapping application.

Prerequisites

Steps

Get the starter app

Select a type of authentication and follow the steps to create a new app.

Set up authentication

Set developer credentials

Use the API key or OAuth developer credentialsDeveloper credentials are a type of item in a portal that contains parameters for authentication. There are two types of developer credentials: API key credentials and OAuth credentials.Learn more so your application can access ArcGIS servicesA service, also known as an ArcGIS service, is software that supports an ArcGIS REST API and provides geospatial functionality or data. A service can be hosted by Esri or in ArcGIS Enterprise.Learn more.

Update the map

1. Remove the basemap and attribution code from the starter tutorial for now. You will add them back later.

   Use dark colors for code blocks

   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
   72
   73
   74
   75
   76
   77
   78
   79
   80
   81
   82
   83
   84
   85
   86
   87
   88
   89
   90
   91
   92
   93
   94
   95
   96
       <script>
   
       /* Use for API key authentication */
       const accessToken = "YOUR_ACCESS_TOKEN";
   
   
       // or
   
       /* Use for user authentication */
       // const session = await arcgisRest.ArcGISIdentityManager.beginOAuth2({
       //   clientId: "YOUR_CLIENT_ID", // Your client ID from OAuth credentials
       //   redirectUri: "YOUR_REDIRECT_URI", // The redirect URL registered in your OAuth credentials
       //   portal: "https://www.arcgis.com/sharing/rest" // Your portal URL
       // })
   
       // const accessToken = session.token;
   
       const basemapEnum = "arcgis/navigation";
       const baseUrl = "https://static-map-tiles-api.arcgis.com/arcgis/rest/services/static-basemap-tiles-service/v1";
   
       const map = new maplibregl.Map({
         container: "map",
   
         style: {
           version: 8,
           sources: {
             "raster-tiles": {
               type: "raster",
               tiles: [
                 `${baseUrl}/${basemapEnum}/static/tile/{z}/{y}/{x}?token=${accessToken}`
               ],
               tileSize: 512
             }
           },
           layers: [
             {
               id: "simple-tiles",
               type: "raster",
               source: "raster-tiles",
               minzoom: 0,
               maxzoom: 22
             }
           ]
         },
   
         zoom: 2,
         center: [-20, 30]
       });
   
       fetch(`${baseUrl}/${basemapEnum}/static?token=${accessToken}`) // Display required Esri and data attribution
         .then((response) => response.json())
         .then((data) => {
           map._controls[0]._innerContainer.innerText += " | Powered by Esri | " + data.copyrightText;
         });
   
       </script>
   

2. Change the map's center to [-91.2996, 37.1174] and zoom level to 4. This will focus the map on the United States of America.

   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
   72
   73
   74
   75
   76
   77
   78
   79
   80
   81
   82
   83
   84
   85
   86
   87
   88
   89
   90
   91
   92
   93
   94
   95
   96
   97
   98
   99
   100
         const map = new maplibregl.Map({
           container: "map",
   
           zoom: 4,
           center: [-91.2996, 37.1174] // USA (x, y)
   
         });
   

Add basemap layer 1

Create a tile source and tile layer to access and display basemap layer from the World Imagery map tile serviceA map tile service, formerly known as image tile service, is a data service that provides access to static, pre-rendered mao tiles. The tiles are typical in PNG format. Map tiles are typically retrieved by specifying a specific level, row, and column value.Learn more.

1. Define a tileSource to load raster tiles from the World Imagery map tile service.

   Expand

   Use dark colors for code blocks

   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
   72
   73
   74
   75
   76
   77
   78
   79
   80
   81
   82
   83
   84
   85
   86
   87
   88
   89
   90
   91
   92
   93
   94
   95
   96
   97
   98
   99
   100
         const tileSource = {
           imagery: {
             type: "raster",
             tiles: [`https://ibasemaps-api.arcgis.com/arcgis/rest/services/World_Imagery/MapServer/tile/{z}/{y}/{x}?token=${accessToken}`],
   
           }
         };
   
   

   Expand

2. Add the data attributionData attribution is the requirement to display the names of data source providers in all applications when accessing ArcGIS content, layers, or services.Learn more for the map tile layer source.

   • Go to the World Imagery itemAn item, also known as a content item, is a resource stored in a portal such as a web map, hosted layer, style, script tool, file, or notebook.Learn more.
   • Scroll down to the Acknowledgments section and copy its value.
   • Paste the copied value to the attribution property.
     Expand

     Use dark colors for code blocks

     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
     72
     73
     74
     75
     76
     77
     78
     79
     80
     81
     82
     83
     84
     85
     86
     87
     88
     89
     90
     91
     92
     93
     94
     95
     96
     97
     98
     99
     100
           const tileSource = {
             imagery: {
               type: "raster",
               tiles: [`https://ibasemaps-api.arcgis.com/arcgis/rest/services/World_Imagery/MapServer/tile/{z}/{y}/{x}?token=${accessToken}`],
     
               attribution: "Esri, Maxar, Earthstar Geographics, and the GIS User Community"
     
             }
           };
     
     

     Expand

3. Define a tileLayer that references the tileSource.

   Expand

   Use dark colors for code blocks

   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
   72
   73
   74
   75
   76
   77
   78
   79
   80
   81
   82
   83
   84
   85
   86
   87
   88
   89
   90
   91
   92
   93
   94
   95
   96
   97
   98
   99
   100
         const tileSource = {
           imagery: {
             type: "raster",
             tiles: [`https://ibasemaps-api.arcgis.com/arcgis/rest/services/World_Imagery/MapServer/tile/{z}/{y}/{x}?token=${accessToken}`],
   
             attribution: "Esri, Maxar, Earthstar Geographics, and the GIS User Community"
   
           }
         };
   
         const tileLayer = {
           id: "imagery-raster",
           type: "raster",
           source: "imagery"
         };
   

   Expand

Add basemap layer 2

In this step, you add another basemap layer from the Static Basemap Tiles serviceThe ArcGIS Static Basemap Tiles service, also known as the Static Basemap Tiles service, is a location service that provides basemap data as pre-rendered and pre-styled map tiles for the world. It supports key styles in the ArcGIS Basemap style family. An ArcGIS Location Platform account is required to use the services.Learn more to provide place labels.

1. Replace basemapEnum to arcgis/imagery/labels and baseUrl to the Static Basemap Tiles service endpoint.

   Expand

   Use dark colors for code blocks

   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
   72
   73
   74
   75
   76
   77
   78
   79
   80
   81
   82
   83
   84
   85
   86
   87
   88
   89
   90
   91
   92
   93
   94
   95
   96
   97
   98
   99
   100
         const basemapEnum = "arcgis/imagery/labels";
         const baseUrl = "https://static-map-tiles-api.arcgis.com/arcgis/rest/services/static-basemap-tiles-service/v1";
   
   

   Expand

2. Create a staticBasemapTileSource using the service.

   Expand

   Use dark colors for code blocks

   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
   72
   73
   74
   75
   76
   77
   78
   79
   80
   81
   82
   83
   84
   85
   86
   87
   88
   89
   90
   91
   92
   93
   94
   95
   96
   97
   98
   99
   100
         const basemapEnum = "arcgis/imagery/labels";
         const baseUrl = "https://static-map-tiles-api.arcgis.com/arcgis/rest/services/static-basemap-tiles-service/v1";
   
         const staticBasemapTileSource = {
           "raster-tiles": {
             type: "raster",
             tiles: [`${baseUrl}/${basemapEnum}/static/tile/{z}/{y}/{x}?token=${accessToken}`],
             tileSize: 512,
             attribution:
               "Powered by <a href='https://www.esri.com/en-us/home' target='_blank'>Esri</a> | Sources: Esri, TomTom, Garmin, FAO, NOAA, USGS, © OpenStreetMap contributors, and the GIS User Community"
           }
         };
   
   

   Expand

3. Add a staticBasemapTileLayer that references the basemap source.

   Expand

   Use dark colors for code blocks

   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
   72
   73
   74
   75
   76
   77
   78
   79
   80
   81
   82
   83
   84
   85
   86
   87
   88
   89
   90
   91
   92
   93
   94
   95
   96
   97
   98
   99
   100
         const basemapEnum = "arcgis/imagery/labels";
         const baseUrl = "https://static-map-tiles-api.arcgis.com/arcgis/rest/services/static-basemap-tiles-service/v1";
   
         const staticBasemapTileSource = {
           "raster-tiles": {
             type: "raster",
             tiles: [`${baseUrl}/${basemapEnum}/static/tile/{z}/{y}/{x}?token=${accessToken}`],
             tileSize: 512,
             attribution:
               "Powered by <a href='https://www.esri.com/en-us/home' target='_blank'>Esri</a> | Sources: Esri, TomTom, Garmin, FAO, NOAA, USGS, © OpenStreetMap contributors, and the GIS User Community"
           }
         };
   
         const staticBasemapTileLayer = {
           id: "static-basemap-tiles",
           type: "raster",
           source: "raster-tiles",
           minzoom: 0,
           maxzoom: 22
         };
   

   Expand

4. Add both sources and both layers to the map. Make sure that tileLayer is added first, followed by staticBasemapTileLayer, so the static basemap tile layer appears on top of the map tile layer.

   Expand

   Use dark colors for code blocks

   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
   72
   73
   74
   75
   76
   77
   78
   79
   80
   81
   82
   83
   84
   85
   86
   87
   88
   89
   90
   91
   92
   93
   94
   95
   96
   97
   98
   99
   100
         const map = new maplibregl.Map({
           container: "map",
   
           style: {
             version: 8,
             sources: { ...tileSource, ...staticBasemapTileSource },
             layers: [tileLayer, staticBasemapTileLayer]
           },
   
           zoom: 4,
           center: [-91.2996, 37.1174] // USA (x, y)
   
         });
   

   Expand

Run the app

Run the app.

The map should display basemap layers from the World Imagery map tile serviceA map tile service, formerly known as image tile service, is a data service that provides access to static, pre-rendered mao tiles. The tiles are typical in PNG format. Map tiles are typically retrieved by specifying a specific level, row, and column value.Learn more and the Static Basemap Tiles serviceThe ArcGIS Static Basemap Tiles service, also known as the Static Basemap Tiles service, is a location service that provides basemap data as pre-rendered and pre-styled map tiles for the world. It supports key styles in the ArcGIS Basemap style family. An ArcGIS Location Platform account is required to use the services.Learn more.

What's next?

Learn how to use additional location services in these tutorials: