Add a raster tile layer

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

A raster tile layer, also known as an image tile layer, displays imagery such as satellite photography or hillshading. You can combine raster 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 raster 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 Hillshade raster tile layer, which is a basemap layer composed of jpeg images, on top of a street basemap layer.

Prerequisites

You need an ArcGIS account to access the developer dashboard and create an API key.

Steps

Create a new pen

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

Set the API key

To access location services, you need an API key or OAuth 2.0 access token.

  1. Go to your dashboard to get an API key. The API key must be scoped to access the services used in this tutorial.

  2. In CodePen, update apiKey to use your key.

    Change line
        
    1
    2
    3
    4
    const apiKey = "YOUR_API_KEY";
    const basemapId = "ArcGIS:Streets";
    const basemapURL = "https://basemaps-api.arcgis.com/arcgis/rest/services/styles/" + basemapId + "?type=style&token=" + apiKey;
    olms(map, basemapURL);
    

Create an image tile layer

To load the hillshade 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 hillshade layer.

The URL for the hillshade image tile layer is:

 
1
https://server.arcgisonline.com/ArcGIS/rest/services/Elevation/World_Hillshade/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 hillshade layer.

    Add line.Add line.Add line.Add line.Add line.Add line.
                                                                        
    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
    <!DOCTYPE html>
    <html>
      <head>
        <meta charset="utf-8" />
        <meta name="viewport" content="initial-scale=1, maximum-scale=1, user-scalable=no" />
        <title>OpenLayers Tutorials: Add a styled basemap layer</title>
    
        <style>
          html,
          body,
          #map {
            padding: 0;
            margin: 0;
            height: 100%;
            width: 100%;
            font-family: Arial, Helvetica, sans-serif;
            font-size: 14px;
            color: #323232;
        </style>
    
        <link rel="stylesheet" href="https://cdn.jsdelivr.net/gh/openlayers/openlayers.github.io@master/en/v6.4.3/css/ol.css" type="text/css" />
        <script src="https://cdn.jsdelivr.net/gh/openlayers/openlayers.github.io@master/en/v6.4.3/build/ol.js"></script>
        <script src="https://cdn.jsdelivr.net/npm/ol-mapbox-style@6.1.4/dist/olms.js" type="text/javascript"></script>
    
      </head>
      <body>
        <div id="map"></div>
    
        <script>
          const apiKey = "YOUR_API_KEY";
          const map = new ol.Map({
            target: "map"
            new ol.View({
              center: ol.proj.fromLonLat([-118.805, 34.027]),
              zoom: 12
          const basemapId = "ArcGIS:Streets";
    
          const basemapURL = "https://basemaps-api.arcgis.com/arcgis/rest/services/styles/" + basemapId + "?type=style&token=" + apiKey;
    
          olms(map, basemapURL)
    
          .then(function (map) {
            const hillshadeURL = "https://server.arcgisonline.com/ArcGIS/rest/services/Elevation/World_Hillshade/MapServer/tile/{z}/{y}/{x}";
    
            const hillshadeSource = new ol.source.XYZ({
              url: hillshadeURL
            });
            const tileLayer = new ol.layer.Tile({
              source: hillshadeSource,
              opacity: 0.3
        </script>
    
      </body>
    </html>
  2. Create a Tile layer using the XYZ source, with 0.3 opacity. Add it to the map using map.addLayer.

    Add line.Add line.Add line.Add line.Add line.
                                                                        
    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
    <!DOCTYPE html>
    <html>
      <head>
        <meta charset="utf-8" />
        <meta name="viewport" content="initial-scale=1, maximum-scale=1, user-scalable=no" />
        <title>OpenLayers Tutorials: Add a styled basemap layer</title>
    
        <style>
          html,
          body,
          #map {
            padding: 0;
            margin: 0;
            height: 100%;
            width: 100%;
            font-family: Arial, Helvetica, sans-serif;
            font-size: 14px;
            color: #323232;
        </style>
    
        <link rel="stylesheet" href="https://cdn.jsdelivr.net/gh/openlayers/openlayers.github.io@master/en/v6.4.3/css/ol.css" type="text/css" />
        <script src="https://cdn.jsdelivr.net/gh/openlayers/openlayers.github.io@master/en/v6.4.3/build/ol.js"></script>
        <script src="https://cdn.jsdelivr.net/npm/ol-mapbox-style@6.1.4/dist/olms.js" type="text/javascript"></script>
    
      </head>
      <body>
        <div id="map"></div>
    
        <script>
          const apiKey = "YOUR_API_KEY";
          const map = new ol.Map({
            target: "map"
            new ol.View({
              center: ol.proj.fromLonLat([-118.805, 34.027]),
              zoom: 12
          const basemapId = "ArcGIS:Streets";
          const basemapURL = "https://basemaps-api.arcgis.com/arcgis/rest/services/styles/" + basemapId + "?type=style&token=" + apiKey;
          .then(function (map) {
            const hillshadeURL = "https://server.arcgisonline.com/ArcGIS/rest/services/Elevation/World_Hillshade/MapServer/tile/{z}/{y}/{x}";
    
            const hillshadeSource = new ol.source.XYZ({
              url: hillshadeURL
            });
    
            const tileLayer = new ol.layer.Tile({
              source: hillshadeSource,
              opacity: 0.3
            });
            map.addLayer(tileLayer);
        </script>
    
      </body>
    </html>

Run the app

In CodePen, run your code to display the map.

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

What's next?

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

Your browser is no longer supported. Please upgrade your browser for the best experience. See our browser deprecation post for more details.