Add a map tile layer

Learn how to add a map tile layer to a map.

A map tile layer, also known as an image tile layer, displays raster images such as satellite photography or hillshading. You can combine map tile layers to enhance the display of a street basemap layer, position the layer on top of existing layers, or position it under existing layers. When positioned above other layers, you need to give the map tile layer a level of transparency so that users can see through it to the basemap. This combined basemap layer technique is used to enhance overall visualization.

In this tutorial, you add a Santa Monica contours map tile layer, which is a basemap layer composed of jpeg images, on top of a street basemap layer.

Prerequisites

Steps

Create a new pen

1. To get started, either complete the Display a map tutorial or use this pen.

Get an access token

You need an access token with the correct privileges to access the resources used in this tutorial.

1. Go to the Create an API key tutorial and create an API key with the following privilege(s):
   

   • Privileges
     • Location services > Basemaps
   • Item access
     • Note: If you are using your own custom data layer for this tutorial, you need to grant the API key credentials access to the layer item. Learn more in Item access privileges.

2. Copy the API key access token to your clipboard when prompted.

3. In CodePen, update the accessToken variable to use your access token.

   Use dark colors for code blocks

   1
   2
   3
   4
   5
   6
   7
   8
   9
   10
   11
   const accessToken = "YOUR_ACCESS_TOKEN";
   const basemapId = "arcgis/streets";
   const basemapURL = `https://basemapstyles-api.arcgis.com/arcgis/rest/services/styles/v2/styles/${basemapId}?token=${accessToken}`;
   olms.apply(map, basemapURL);
   

To learn about the other types of authentication available, go to Types of authentication.

Update the map

1. Center the map on [-118.44, 34.03]. This will set the map focus to Santa Monica, California.

   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
         map.setView(
           new ol.View({
   
             center: ol.proj.fromLonLat([-118.44, 34.03]),
   
             zoom: 12
           })
         );
   

   Expand

Create a tile layer

To load the contour tiles, you will create an XYZ source, using an XYZ URL. This is a URL with {x}, {y} and {z} elements which the source substitutes with numbers when requesting each tile. The source can be displayed using a Tile layer with the source property. Set the opacity to 0.3 so that the basemap can be seen through the contours layer.

The URL for the Santa Monica contours map tile service is:

1
https://services3.arcgis.com/GVgbJbqm8hXASVYi/arcgis/rest/services/Santa_Monica_contours_(map_tiles)/MapServer/tile/{z}/{y}/{x}

1. Add a load handler to the olms initialization. Inside, create an XYZ source using the XYZ url for the contours 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
         const basemapId = "arcgis/light-gray";
   
         const basemapURL = `https://basemapstyles-api.arcgis.com/arcgis/rest/services/styles/v2/styles/${basemapId}?token=${accessToken}`;
   
         olms.apply(map, basemapURL)
   
           .then(function (map) {
             const contoursURL = "https://services3.arcgis.com/GVgbJbqm8hXASVYi/arcgis/rest/services/Santa_Monica_contours_(map_tiles)/MapServer/tile/{z}/{y}/{x}";
   
             const contoursSource = new ol.source.XYZ({
               url: contoursURL
             });
   

   Expand

2. Create a Tile layer using the XYZ source, with 0.3 opacity. Add it to the map using map.addLayer.

   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
           .then(function (map) {
             const contoursURL = "https://services3.arcgis.com/GVgbJbqm8hXASVYi/arcgis/rest/services/Santa_Monica_contours_(map_tiles)/MapServer/tile/{z}/{y}/{x}";
   
             const contoursSource = new ol.source.XYZ({
               url: contoursURL
             });
   
             const tileLayer = new ol.layer.Tile({
               source: contoursSource,
               opacity: 0.3
             });
   
             map.addLayer(tileLayer);
   

   Expand

Run the app

In CodePen, run your code to display the map.

Your map should display a semi-transparent contours layer overlaid over a basemap.

What's next?

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