Add a map tile layer

Learn how to add a to a .

Add a raster tile layer using API key authentication

A map tile layer, also known as an , displays raster imagery such as satellite photography or hillshading. You can combine map tile layers to enhance the display of a street , 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 composed of JPEG images, on top of a street basemap layer.

Prerequisites

Steps

Get the starter app

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

You can choose one of the following to create a new CodePen:

  • Option 1: Complete the Display a map tutorial; or,
  • Option 2: Start from the Display a map tutorial .

Set up authentication

Create in your for the type of authentication you selected.

Create a new with the correct privileges to access the resources used in this tutorial.

  1. Go to the Create an API key tutorial and create an with the following :
    • Privileges
      • Location services > Basemaps
    • Item access
      • Note: If you are using your own custom data layer for this tutorial, you need to grant the access to the layer item. Learn more in Item access privileges.
  2. Copy the API key access token to your clipboard when prompted.

Set developer credentials

Use the API key or OAuth so your application can access .

  1. Update the accessToken variable to use your API key.

    Expand
    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
        /* Use for API key authentication */
        const accessToken = "YOUR_ACCESS_TOKEN"
    
    Expand

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
    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
      <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 basemapEnum = "arcgis/light-gray";
    
        const map = new maplibregl.Map({
          container: "map", // the id of the div element
          style: `https://basemapstyles-api.arcgis.com/arcgis/rest/services/styles/v2/styles/${basemapEnum}?token=${accessToken}`,
    
          zoom: 11, // starting zoom
          center: [-118.44, 34.03] // starting location [longitude, latitude]
    
        });
    
        // Add Esri attribution
        // Learn more in https://esriurl.com/attribution
        map._controls[0].options.customAttribution += " | Powered by Esri "
        map._controls[0]._updateAttributions()
    
      </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.

    Expand
    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
      <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 basemapEnum = "arcgis/light-gray";
    
        const map = new maplibregl.Map({
          container: "map", // the id of the div element
          style: `https://basemapstyles-api.arcgis.com/arcgis/rest/services/styles/v2/styles/${basemapEnum}?token=${accessToken}`,
    
          zoom: 11, // starting zoom
          center: [-118.44, 34.03] // starting location [longitude, latitude]
    
        });
    
        map.once("load", () => {
          // This code runs once the base style has finished loading.
    
        });
    
        // Add Esri attribution
        // Learn more in https://esriurl.com/attribution
        map._controls[0].options.customAttribution += " | Powered by Esri "
        map._controls[0]._updateAttributions()
    
      </script>
    
    Expand

Add a raster source

You need to define a 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.

    Expand
    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
        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 for the map tile source.

    • Go to the Santa Monica Mountains countours .
    • Scroll down to the Credits (Attribution) section and copy its value.
    • Create an attribution property and paste the attribution value from the item.
      Expand
      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
          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 of type raster.

  1. Add a raster layer with id contours-raster, connected to the contours source.

    Expand
    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
        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 . To visually combine contours with roads and park layers, you need to make two changes.

  1. Move the contours layer below every layer except the background layer. You do this by passing the id of the next layer as an extra argument to map.addLayer.

  2. Reduce the opacity of basemap elements so the contours layer can be seen through them. In the ArcGIS:Streets basemap, this includes several layers whose ids begin with Water area, Marine area, Bathymetry or Building. You can use map.getStyle to get the current style, and its layers property to access all layers. Use map.setPaintProperty to change the fill-opacity for each layer.

  3. 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
    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
          // 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
  4. Set 50% fill-opacity for every fill layer except water and building layers.

    Expand
    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
            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 overlaid over a basemap. You should see the contours layer combined with other layers, with labels, roads, buildings and water areas clearly visible over the top.

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.

You can no longer sign into this site. Go to your ArcGIS portal or the ArcGIS Location Platform dashboard to perform management tasks.

Your ArcGIS portal

Create, manage, and access API keys and OAuth 2.0 developer credentials, hosted layers, and data services.

Your ArcGIS Location Platform dashboard

Manage billing, monitor service usage, and access additional resources.

Learn more about these changes in the What's new in Esri Developers June 2024 blog post.

Close