Add a map tile layer

Learn how to add a map tile layerA hosted map tile layer is a hosted layer (item) in a portal that is used to manage the properties and settings of a map tile service.Learn more to a mapA map is a collection of layers that are displayed in 2D. It is typically composed of a basemap layer and data layers.Learn more.

A map tile layer displays raster imagery such as satellite photography or hillshading. You can combine map tile layers to enhance the display of a street basemapA basemap is the foundational layer and data that provides the overall visual and geographic context for a map or scene. It typically includes geographic features and labels for land, water, roads, buildings, cities, places, and administrative boundaries, but can also include raster data such as satellite and areal images.Learn more, position the layer on top of existing layers, or position it under existing layers.

In this tutorial, you add a Santa Monica contours map tile layer on top of a basemap.

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. Center the map on [-118.44, 34.03] and set the zoom level to 11. This will set the map focus to Santa Monica, California.

   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
   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
   101
   102
       <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: "YOUR_PORTAL_URL" // Your portal URL
       // })
   
       // const accessToken = session.token;
       const map = new maplibregl.Map({
         container: "map", // the id of the div element
   
         zoom: 11, // starting zoom
         center: [-118.44, 34.03] // starting location [longitude, latitude]
   
       });
       const basemapStyle = maplibreArcGIS.BasemapStyle.applyStyle(map, {
         style: "arcgis/light-gray",
         token: accessToken
       });
   
       </script>
   

   Expand

Add a load event handler

To add layers to the map, you need to use the load event to ensure the map is fully loaded.

1. Add an event handler for the load event.

   More info

   For more information about the load event, see the MapLibre GL JS documentation.

   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
   101
   102
       <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: "YOUR_PORTAL_URL" // Your portal URL
       // })
   
       // const accessToken = session.token;
       const map = new maplibregl.Map({
         container: "map", // the id of the div element
   
         zoom: 11, // starting zoom
         center: [-118.44, 34.03] // starting location [longitude, latitude]
   
       });
       const basemapStyle = maplibreArcGIS.BasemapStyle.applyStyle(map, {
         style: "arcgis/light-gray",
         token: accessToken
       });
   
       map.once("load", () => {
         // This code runs once the base style has finished loading.
   
       });
   
       </script>
   

   Expand

Add a raster source

You need to define a sourceA source in Mapbox GL JS is a file or service that supplies data for a layer displayed in a map.Learn more for the map tiles. This tells the Map how to access the data for the layer, but does not display it.

1. Inside the load event handler, add a raster source with id contours.

   More info

   While there are several types of source, the most common are vector for vector tiles, raster for map tiles, and geojson for a set of features represented as GeoJSON.

   For more information, see the MapLibre Style Specification

   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
   101
   102
       map.once("load", () => {
         // This code runs once the base style has finished loading.
   
         map.addSource("contours", {
           type: "raster",
           tiles: [
             "https://services3.arcgis.com/GVgbJbqm8hXASVYi/arcgis/rest/services/Santa_Monica_contours_(map_tiles)/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 source.

   • Go to the Santa Monica Mountains contours 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
     101
     102
         map.once("load", () => {
           // This code runs once the base style has finished loading.
     
           map.addSource("contours", {
             type: "raster",
             tiles: [
               "https://services3.arcgis.com/GVgbJbqm8hXASVYi/arcgis/rest/services/Santa_Monica_contours_(map_tiles)/MapServer/tile/{z}/{y}/{x}?token=" + accessToken
             ],
     
             // Attribution text retrieved from https://arcgis.com/home/item.html?id=5fd812155876416997c1a03e841e8821
             attribution: "City of Santa Monica GIS Data"
     
           });
     
         });
     

     Expand

Add a raster layer

To display the map tiles, add a layerA layer in Mapbox GL JS is a visual element that displays data from a source.Learn more of type raster.

1. Add a raster layer with id contours-raster, connected to the contours 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
   101
   102
       map.once("load", () => {
         // This code runs once the base style has finished loading.
   
         map.addSource("contours", {
           type: "raster",
           tiles: [
             "https://services3.arcgis.com/GVgbJbqm8hXASVYi/arcgis/rest/services/Santa_Monica_contours_(map_tiles)/MapServer/tile/{z}/{y}/{x}?token=" + accessToken
           ],
   
           // Attribution text retrieved from https://arcgis.com/home/item.html?id=5fd812155876416997c1a03e841e8821
           attribution: "City of Santa Monica GIS Data"
   
         });
   
         map.addLayer(
           {
             id: "contours-raster",
             type: "raster",
             source: "contours"
           },
   
         );
   
       });
   

   Expand

2. At the top right, click Run. You should see the contours layer only.

Adjust the basemap

By default, the contours layer is added on top of all the basemap layersA layer in Mapbox GL JS is a visual element that displays data from a source.Learn more. To visually combine contours with roads and park layers, you need to make two changes.

1. In the load handler, find the id of the first non-background layer. Modify your addLayer call to insert the raster layer before that 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
   101
   102
         // Find the first non-background layer in order to add our raster layer before it.
         const layers = map.getStyle().layers;
         const bottomLayer = layers.find((layer) => layer.type !== "background");
   
         map.addLayer(
           {
             id: "contours-raster",
             type: "raster",
             source: "contours"
           },
   
           bottomLayer.id
   
         );
   

   Expand

2. Set 50% fill-opacity for every fill layer except water and building layers.

   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
   101
   102
           bottomLayer.id
   
         );
   
         layers.forEach((layer) => {
           if (layer.type === "fill" && !layer.id.match(/(Water area|Marine area|Bathymetry|Building)/)) {
             map.setPaintProperty(layer.id, "fill-opacity", 0.5);
           }
         });
   

   Expand

Run the app

Run the app.

Your map should display a semi-transparent contours layer on top of a basemap.

What's next?

Learn how to use additional location services in these tutorials: