Overlay basemap layers

Learn how to overlay a static basemap layer with a map tile layer.

The static basemap tiles service provides access to raster basemap tiles for the world. The service supports a number of ArcGIS styles, including arcgis/imagery/labels and arcgis/oceans/labels that you can overlay on top of existing map tile layers.

In this tutorial, you overlay the arcgis/imagery/labels static basemap tiles with the World Imagery tile layer to provide place labels and geographic context.

Prerequisites

Steps

Get the starter app

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

Set up authentication

Create developer credentials in your portal for the type of authentication you selected.

Set developer credentials

Use the API key or OAuth developer credentials so your application can access location services.

Update the map's viewpoint

1. 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 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
         const map = new maplibregl.Map({
           container: "map",
   
           zoom: 4,
           center: [-91.2996, 37.1174] // USA (x, y)
   
         });
   

Add map tile layer

Create a tile source and tile layer to access and display data from the World Imagery map tile service.

1. Define a tileSource to load raster tiles from the World Imagery Map 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
         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 attribution for the map tile layer source.

   • Go to the World Imagery item.
   • Scroll down to the Credits (Attribution) section and copy its value.
   • Create an attribution property and paste the attribution value from the item.
     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
           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
         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

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
         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 basemapSource using the static basemap tiles service. This source will serve raster tiles for the basemap.

   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
         const basemapEnum = "arcgis/imagery/labels";
         const baseUrl = `https://static-map-tiles-api.arcgis.com/arcgis/rest/services/static-basemap-tiles-service/v1`;
   
         const basemapSource = {
           "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 basemapLayer 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
         const basemapEnum = "arcgis/imagery/labels";
         const baseUrl = `https://static-map-tiles-api.arcgis.com/arcgis/rest/services/static-basemap-tiles-service/v1`;
   
         const basemapSource = {
           "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 basemapLayer = {
           id: "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 basemapLayer, so the basemap layer appears on top of the 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
         const map = new maplibregl.Map({
           container: "map",
   
           style: {
             version: 8,
             sources: { ...tileSource, ...basemapSource },
             layers: [tileLayer, basemapLayer]
           },
   
           zoom: 4,
           center: [-91.2996, 37.1174] // USA (x, y)
   
         });
   

   Expand

Run the app

Run the app.

The map should display map tiles from the World Imagery map tile service overlaid with labels from the static basemap tiles service.

What's next?

Learn how to use additional ArcGIS location services in these tutorials: